Iskanje

GET /v1/entities združuje iskanje po imenu (q) in filtriranje. GET /v1/autocomplete je lahka različica za obrazce.

Kaj je v q

Niz najprej normaliziramo:

1. Identifikator? Odstranimo presledke, . in -, pretvorimo v velike črke in odstranimo SI. Če ostanejo samo števke: 8 števk je davčna številka, 7 ali 10 matična. Druga dolžina vrne 422.
2. Šumniki in naglasi se poenotijo: č→c, š→s, ž→z, ć→c, đ→d. cebelica, Čebelica in ČEBELICA so isto.
3. Pravne oblike (doo, d.o.o., d o o, dd, d.d., sp, s.p., zavod, drustvo, …) odstranimo iz besedila in jih uporabimo kot blag dvig ranga. Če želite strogo filtrirati, uporabite legal_form=.
4. Mašila (in, za, …) izpustimo.
5. Potrebna je vsaj ena beseda s 3 ali več znaki, sicer 422 query_too_short.

q	Najde
cebelica	ČEBELICA d.o.o., ČEBELICA MAJA … s.p.
cebelica doo	najprej ČEBELICA d.o.o. (dvig za pravno obliko)
gasilska oprema	GASILSKA OPREMA VZOREC, D.O.O.
gasilsk opr	isto: vse besede kot predpone
SI 1900-0006	iskanje po davčni številki 19000006

Iskanje prenese tipkarske napake (trigrami) in ne uporablja krnjenja, da ne meša lastnih imen.

Filtri

Parameter	Primer	Opomba
type	legal_entity, sole_proprietor, other_self_employed
status	active, inactive
postal_code	1000
city	ljubljana	poenoteni šumniki
activity_code	62 ali 62.010	predpona SKD 2025
vat_registered	true
legal_form	d.o.o.	strog filter
tax_office	08	šifra finančnega urada
sort	relevance (privzeto z q), name, tax_number
limit	20	privzeto 20, največ 50

Brez q dobite filtriran seznam, urejen po davčni številki.

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

Vsak zadetek ima polje match z oceno in polji, na katerih se je ujel:

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

Fizične osebe (s.p.)

S.p. in druge fizične osebe z dejavnostjo so iskalni enako kot pravne osebe, razen če je oseba ugovarjala iskanju po imenu (zapis je takrat dosegljiv samo po točni davčni ali matični). Za fizične osebe veljata nižja globina (50 zadetkov na iskanje) in dnevna omejitev različnih oseb na organizacijo; glej Omejitve.

Samodokončanje

GET /v1/autocomplete?q=cebel&limit=5 vrne lahke zapise (davčna, ime, pravna oblika, kraj, pošta, DDV) za 0,25 enote. Deluje z javnimi ključi.

• Zahtevo pošljite šele po 3 znakih.
• Uporabite zakasnitev 150–250 ms (debounce) in prekličite prejšnjo zahtevo (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);
});