Search

GET /v1/entities combines name search (q) and filtering. GET /v1/autocomplete is a lightweight variant for forms.

What goes into q

The string is normalised first:

1. An identifier? We strip spaces, . and -, upper-case it and drop SI. If only digits remain: 8 digits is a tax number, 7 or 10 a registration number. Any other length returns 422.
2. Diacritics and accents are folded: č→c, š→s, ž→z, ć→c, đ→d. cebelica, Čebelica and ČEBELICA are the same.
3. Legal forms (doo, d.o.o., d o o, dd, d.d., sp, s.p., zavod, drustvo, …) are removed from the text and used as a gentle ranking boost. For a strict filter, use legal_form=.
4. Stop words (in, za, …) are dropped.
5. At least one word of 3 or more characters is required, otherwise 422 query_too_short.

q	Finds
cebelica	ČEBELICA d.o.o., ČEBELICA MAJA … s.p.
cebelica doo	ČEBELICA d.o.o. first (legal-form boost)
gasilska oprema	GASILSKA OPREMA VZOREC, D.O.O.
gasilsk opr	the same: every word as a prefix
SI 1900-0006	lookup by tax number 19000006

Search tolerates typos (trigrams) and does not use stemming, so proper names are not conflated.

Filters

Parameter	Example	Note
type	legal_entity, sole_proprietor, other_self_employed
status	active, inactive
postal_code	1000
city	ljubljana	diacritics folded
activity_code	62 or 62.010	SKD 2025 prefix
vat_registered	true
legal_form	d.o.o.	strict filter
tax_office	08	tax office code
sort	relevance (default with q), name, tax_number
limit	20	default 20, at most 50

Without q you get a filtered list ordered by tax number.

curl "https://api.maticna.si/v1/entities?q=cebelica&city=ljubljana&vat_registered=true" \
  -H "Authorization: Bearer $MATICNA_KEY"

Every hit has a match field with the score and the fields it matched on:

{ "match": { "score": 171.4, "matched_on": ["name"] } }

Natural persons (s.p.)

Sole proprietors and other natural persons carrying out an activity are searchable just like legal entities, unless the person has objected to name search (the record is then reachable only by exact tax or registration number). Natural persons have a lower depth (50 results per search) and a daily cap on distinct persons per organisation; see Rate limits.

Autocomplete

GET /v1/autocomplete?q=cebel&limit=5 returns lightweight records (tax number, name, legal form, city, postal code, VAT) for 0.25 units. It works with publishable keys.

• Send the request only after 3 characters.
• Use a 150–250 ms debounce and cancel the previous request (AbortController).

let timer, ctrl;
input.addEventListener('input', () => {
  clearTimeout(timer);
  timer = setTimeout(async () => {
    ctrl?.abort();
    ctrl = new AbortController();
    if (input.value.trim().length < 3) return;
    const r = await fetch(`https://api.maticna.si/v1/autocomplete?q=${encodeURIComponent(input.value)}`, {
      headers: { Authorization: 'Bearer mk_pub_…' }, signal: ctrl.signal,
    });
    render((await r.json()).data);
  }, 200);
});