oneapi
Autentificare
Locations v1 / Căutare & rezolvare

Caută locuri (gazetteer)

Căutare unificată peste județe, UAT și localități + denumiri alternative, plus
locurile secundare (cătune/cartiere). Acestea din urmă pot fi excluse cu ?secundare=0.
Răspunsul include și meta actualizat (prospețimea datelor).

GET
https://oneapi.ro/api/locations/v1/cauta

Parametri de interogare

NumeTipDescriereValori acceptate
qopțional string | null Prefixul căutat, peste nume şi denumirile alternative. Fără el, ruta întoarce primele entităţi în ordinea implicită. max 100 car.
judetopțional string | null Indicativul auto al judeţului (CJ, IF, B) — cel pe care îl ştie utilizatorul, nu codul SIRUTA. ex. CJ
nivelopțional string | null Nivelul administrativ: uat sau localitate. uatlocalitate
tipopțional string | null Tipul unităţii (municipiu, oras, comuna, sat…). Denumirile complete sunt la /nomenclatoare/tipuri. max 30 car.
secundareopțional boolean | null Include cătunele/cartierele. Implicit da la /cauta; 0 le exclude. 0 | 1
aliasopțional boolean | null Include potrivirile pe nume alternative (exonime/istorice). Implicit da; 0 = doar numele principal. 0 | 1
limitaopțional integer | null Câte rezultate să întoarcă; implicit 20, maximum 50. 1 – 50

Cum se comportă

  • Caută peste județe, UAT și localități + denumirile lor alternative (exonime, istorice).
  • Cascadă: prefix → substring → fuzzy. Cu diacritice sau fără, e la fel — se normalizează server-side.
  • Când potrivirea vine dintr-un nume alternativ, apare potrivit_ca — afișează-l, altfel userul nu înțelege de ce „Kolozsvár" a întors Cluj-Napoca.
  • Include și locuri secundare — cătune și cartiere (nivel = catun/cartier), fără cod SIRUTA, ancorate la UAT-ul-mamă în parte_din. Rang mai mic decât localitățile oficiale (apar în coadă). Exclude-le cu ?secundare=0.

La ce folosește

  • Căutare generală de locuri într-un portal: userul caută un oraș/comună/sat și primești entitatea oficială cu coordonate și populație.
  • Curățarea unui import cu localități scrise liber (inclusiv exonime maghiare/germane) → entități oficiale prin denumirile alternative.
  • Căutare de adrese fine când vrei și cătunele/cartierele în rezultate, nu doar unitățile oficiale.

Structura răspunsului

CâmpTipDescriere
data[].cod_siruta integer Cheia publică a entității (localitate/UAT). null pentru județe și locuri secundare (cătune/cartiere).
data[].nume string Denumirea entității.
data[].nume_afisare string Nume dezambiguizat pentru omonime („Baia (Suceava)").
data[].nume_ascii string Denumirea fără diacritice, cea folosită la potrivire.
data[].nivel string uat | localitate | catun | cartier.
data[].tip string Tipul entității (cod brut; denumirile la /nomenclatoare/tipuri).
data[].populatie integer Populația (recensământ).
data[].judet string Numele județului entității.
data[].judet_cod string Indicativul auto al județului („CJ").
data[].uat null Numele UAT-ului entității.
data[].lat number Latitudine WGS84 (reședința pentru UAT, punctul locului altfel). null când lipsește.
data[].lng number Longitudine WGS84. null când lipsește.
data[].parte_din object | null Prezent doar la locuri secundare: UAT-ul-mamă la care se ancorează cătunul/cartierul.
data[].potrivit_ca object | null Prezent doar la potrivire pe un nume alternativ.
meta.actualizat.administrativ string Când s-a împrospătat ultima dată chiar setul ăsta de date.
meta.actualizat.populatie string Când s-a împrospătat ultima dată chiar setul ăsta de date.
data[].parte_din.uat UAT-ul din care face parte locul secundar (cătun/cartier).
data[].potrivit_ca.nume Forma de nume care a produs potrivirea (poate fi un alias, nu denumirea canonică).
data[].potrivit_ca.tip Ce fel de nume a potrivit: exonim, denumire istorică, variantă.
data[].potrivit_ca.lang Limba aliasului potrivit, unde e cunoscută.
data[].potrivit_ca.sursa De unde provine aliasul (nomenclator, OSM, Wikidata).
data[].potrivit_ca.valabil_pana_la Anul până la care denumirea a fost oficială, la denumirile istorice.
data[].cod_postal Codul poștal, unde entitatea are unul singur.

Exemple de răspuns

GEThttps://oneapi.ro/api/locations/v1/cauta?q=cluj
{
    "data": [
        {
            "cod_siruta": 54975,
            "nume": "Cluj-Napoca",
            "nume_afisare": "Cluj-Napoca",
            "nume_ascii": "Cluj-Napoca",
            "nivel": "uat",
            "tip": "municipiu",
            "populatie": 286598,
            "judet": "Cluj",
            "judet_cod": "CJ",
            "uat": null,
            "lat": 46.76891,
            "lng": 23.59066,
            "parte_din": null,
            "potrivit_ca": null
        }
    ],
    "meta": {
        "actualizat": {
            "administrativ": "2026-08-15T16: 39: 14+03: 00",
            "populatie": "2026-08-15T16: 40: 07+03: 00"
        }
    }
}

Coduri de eroare

CodSlugCând apare
401neautentificatToken lipsă, invalid, expirat sau revocat.
403feature_indisponibilPlanul curent nu include funcţia de care ţine ruta.
422validareUn parametru nedeclarat ori o valoare care nu trece validarea (q, judet, nivel, tip, secundare, alias, limita). Câmpul vinovat e în detalii.
429cota_depasitaCota lunară a planului a fost depăşită (vezi Retry-After).

Toate erorile au aceeași formă. eroare.cod e stabil și e cel după care trebuie să ramifici în cod — nu după textul din mesaj, care se poate schimba.

{
    "eroare": {
        "cod": "validare",
        "mesaj": "Un parametru nedeclarat ori o valoare care nu trece validarea (q, judet, nivel, tip, secundare, alias, limita). Câmpul vinovat e în detalii.",
        "detalii": {
            "q": [
                "Valoarea trimisă nu respectă regula parametrului."
            ]
        }
    }
}