Locations v1 / Căutare & rezolvare

Autocomplete (typeahead)

Aceeași căutare ca /cauta, dar payload minim pentru un dropdown rapid. Ca picker de
entități oficiale (fiecare cu cod_siruta), NU întoarce locuri secundare (cătune/
cartiere) implicit — trimite ?secundare=1 dacă vrei și pe acelea. Fără meta
actualizat — se apelează la fiecare tastă.

GET

https://oneapi.ro/api/locations/v1/autocomplete

Parametri de interogare

NumeTipDescriereValori acceptate

qopțional string | null Prefixul tastat de utilizator. max 100 car.

judetopțional string | null Indicativul auto al judeţului (CJ, IF, B). ex. CJ

nivelopțional string | null Nivelul administrativ: uat sau localitate. uatlocalitate

tipopțional string | null Tipul unităţii (municipiu, oras, comuna, sat…). max 30 car.

secundareopțional boolean | null Include și cătunele/cartierele. Implicit 0 (doar oficiale). 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ă

Aceleași date ca /cauta, dar payload minim — pentru un dropdown care se declanșează la fiecare tastă.
Ca picker de entități oficiale (fiecare cu cod_siruta), NU întoarce locuri secundare (cătune/cartiere) implicit. Trimite ?secundare=1 dacă vrei și pe acelea.
Fiecare rezultat aduce și judet_cod + lat/lng, ca la selecție să ai direct județul și coordonatele, fără al doilea apel.

La ce folosește

Câmp de localitate cu sugestii instant în checkout: userul tastează, tu arăți entitățile oficiale cu cod_siruta selectabil.
Picker de UAT/localitate într-un panou de configurare (zone de livrare, filiale) — fiecare opțiune aduce deja județul, gata de salvat.
Căutare pe hartă: la selecție ai lat/lng în răspuns și centrezi harta fără un al doilea apel.

Structura răspunsului

Toate câmpurile de mai jos sunt în data[].

CâmpTipDescriere

cod_siruta integer | null Cheia publică (localitate/UAT). null pentru locuri secundare (doar cu ?secundare=1).

nume_afisare string Nume dezambiguizat pentru omonime.

nivel string Nivelul entității: regiune, judet, uat sau localitate.

tip string | null Tipul entității (cod brut; denumirile la /nomenclatoare/tipuri).

judet_cod string | null Indicativul auto al județului („CJ").

lat number | null Latitudine WGS84. null când lipsește.

lng number | null Longitudine WGS84. null când lipsește.

Exemple de răspuns

GEThttps://oneapi.ro/api/locations/v1/autocomplete?q=baia&limita=5

{
    "data": [
        {
            "cod_siruta": 146904,
            "nume_afisare": "Baia (Suceava)",
            "nivel": "uat",
            "tip": "comuna",
            "judet_cod": "SV",
            "lat": 47.4203,
            "lng": 26.2169
        }
    ]
}

Include cătune/cartiere.

GEThttps://oneapi.ro/api/locations/v1/autocomplete?q=someseni&secundare=1

{
    "data": [
        {
            "cod_siruta": 136839,
            "nume_afisare": "Someșeni",
            "nivel": "localitate",
            "tip": "sat",
            "judet_cod": "SM",
            "lat": 47.744089,
            "lng": 23.20641
        }
    ]
}

GEThttps://oneapi.ro/api/locations/v1/autocomplete

{
    "data": [
        {
            "cod_siruta": 179132,
            "nume_afisare": "București",
            "nivel": "uat",
            "tip": "municipiu",
            "judet_cod": "B",
            "lat": 44.413361111111,
            "lng": 26.097777777778
        }
    ]
}

GEThttps://oneapi.ro/api/locations/v1/autocomplete?q=Cluj

{
    "data": [
        {
            "cod_siruta": 54975,
            "nume_afisare": "Cluj-Napoca",
            "nivel": "uat",
            "tip": "municipiu",
            "judet_cod": "CJ",
            "lat": 46.76891,
            "lng": 23.59066
        }
    ]
}

Coduri de eroare

Cod	Slug	Când apare
401	neautentificat	Token lipsă, invalid, expirat sau revocat.
403	feature_indisponibil	Planul curent nu include funcţia de care ţine ruta.
422	validare	Un parametru nedeclarat ori o valoare care nu trece validarea (`q`, `judet`, `nivel`, `tip`, `secundare`, `alias`, `limita`). Câmpul vinovat e în `detalii`.
429	cota_depasita	Cota 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."
            ]
        }
    }
}