oneapi
Autentificare
Locations v1 / Căutare & rezolvare

Rezolvă (dispatcher)

„Ce e string-ul ăsta?" — clasifică input-ul (cod poștal / cod SIRUTA / nume) și
* întoarce entitatea rezolvată + alternative la nume ambiguu. Un endpoint pentru
* „userul a tastat ceva și a dat Enter".

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

Parametri de interogare

NumeTipDescriereValori acceptate
qobligatoriu text Minim 1, maxim 100. max 100 car.

Cum se comportă

  • Dispatcher: clasifică input-ul (cod poștal de 6 cifre → cod SIRUTA → nume) și întoarce entitatea rezolvată.
  • Un string tip adresă rezolvă localitatea din el (ultimul token). Nimic găsit → interpretare: null.
  • Rezolvarea pe nume poate întoarce și un loc secundar (cătun/cartier) când nu există oficial omonim — cu cod_siruta: null și parte_din către UAT-ul-mamă.

La ce folosește

  • Bară de căutare cu Enter: userul tastează orice (cod poștal, cod SIRUTA sau nume) și afișezi direct entitatea, fără să-l pui să aleagă tipul input-ului.
  • Normalizarea unei coloane mixte dintr-un CSV (unele rânduri cod poștal, altele nume de localitate) la entități unice.
  • Deep-link: dintr-un parametru de URL (?loc=cluj-napoca sau ?loc=400001) rezolvi entitatea și încarci pagina ei.

Structura răspunsului

CâmpTipDescriere
data.interpretare string | null cod_postal | cod_siruta | nume | null.
data.rezultat object Entitatea rezolvată (aceeași formă ca un rezultat din /cauta).
data.rezultat.cod_siruta integer | null Codul SIRUTA (cheia publică a entității).
data.rezultat.nume string Denumirea entității.
data.rezultat.nume_afisare string Denumirea pregătită pentru afișare (cu rangul, unde ajută).
data.rezultat.nivel string Nivelul entității: regiune, judet, uat sau localitate.
data.rezultat.tip string | null Tipul entității (cod brut; denumirile la /nomenclatoare/tipuri).
data.rezultat.judet string | null Numele județului entității rezolvate.
data.rezultat.judet_cod string | null Indicativul auto al județului.
data.rezultat.lat number | null Latitudine (WGS84).
data.rezultat.lng number | null Longitudine (WGS84).
data.alternative[] array Alte potriviri, la un nume ambiguu.
data.alternative[].cod_siruta integer | null Codul SIRUTA (cheia publică a entității).
data.alternative[].nume string Denumirea entității.
data.alternative[].nume_afisare string Denumirea pregătită pentru afișare.
data.alternative[].nivel string Nivelul entității: regiune, judet, uat sau localitate.
data.alternative[].tip string | null Tipul entității (cod brut; denumirile la /nomenclatoare/tipuri).
data.alternative[].judet string | null Numele județului alternativei.
data.alternative[].judet_cod string | null Indicativul auto al județului alternativei.
data.alternative[].lat number | null Latitudine (WGS84).
data.alternative[].lng number | null Longitudine (WGS84).
meta.actualizat object Prospețimea datelor pe domenii (dată ISO 8601).

Exemple de răspuns

GEThttps://oneapi.ro/api/locations/v1/rezolva?q=400001
{
    "data": {
        "interpretare": "cod_postal",
        "rezultat": {
            "cod_siruta": 54984,
            "nume": "Cluj-Napoca",
            "nume_afisare": "Cluj-Napoca",
            "nume_ascii": "Cluj-Napoca",
            "nivel": "localitate",
            "tip": "resedinta_municipiu",
            "populatie": 286598,
            "judet": "Cluj",
            "judet_cod": "CJ",
            "uat": "Cluj-Napoca",
            "lat": 46.78,
            "lng": 23.559444444444,
            "parte_din": null,
            "potrivit_ca": null,
            "cod_postal": "400001"
        },
        "alternative": []
    },
    "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.
422parametri_invaliziq lipsește (input-ul de rezolvat e obligatoriu).
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": "parametri_invalizi",
        "mesaj": "q lipsește (input-ul de rezolvat e obligatoriu).",
        "detalii": {
            "q": [
                "Valoarea trimisă nu respectă regula parametrului."
            ]
        }
    }
}