Locations v1 / Căutare & rezolvare

Autocomplete (typeahead)

The same search as /cauta, but with a minimal payload for a fast dropdown. As a picker of official entities (each with a cod_siruta), it does NOT return secondary places (hamlets and neighbourhoods) by default — send ?secundare=1 if you want those too. No actualizat meta — it is called on every keystroke.

GET

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

Query parameters

NameTypeDescriptionAccepted values

qoptional string | null The prefix the user has typed. max 100 car.

judetoptional string | null The county's vehicle registration prefix (CJ, IF, B). e.g. CJ

niveloptional string | null Administrative level: uat or localitate. uatlocalitate

tipoptional string | null Unit type (municipiu, oras, comuna, sat…). max 30 car.

secundareoptional boolean | null Include hamlets and neighbourhoods as well. 0 by default (official entities only). e.g. 1

aliasoptional boolean | null Include matches on alternative names (exonyms, historical). On by default; 0 = main name only.

limitaoptional integer | null How many results to return; 20 by default, 50 at most. 1 – 50

How it behaves

The same data as /cauta, but with a minimal payload — for a dropdown that fires on every keystroke.
As a picker of official entities (each with a cod_siruta), it does NOT return secondary places (hamlets/neighbourhoods) by default. Send ?secundare=1 if you want those too.
Every result also carries judet_cod and lat/lng, so on selection you already have the county and the coordinates, without a second call.

What it is for

A locality field with instant suggestions at checkout: the user types, you show official entities with a selectable cod_siruta.
A unit/locality picker in a settings panel (delivery zones, branches) — each option already carries the county, ready to save.
Map search: on selection you have lat/lng in the response and can centre the map without a second call.

Response structure

All fields below live inside data[].

FieldTypeDescription

cod_siruta integer | null The public key (locality/administrative unit). null for secondary places (only with ?secundare=1).

nume_afisare string Disambiguated name for homonyms.

nivel string The entity level: region, county, administrative unit or locality.

tip string | null Entity type (raw code; the full names are at /nomenclatoare/tipuri).

judet_cod string | null The county's vehicle registration prefix („CJ").

lat number | null Latitude, WGS 84. null when missing.

lng number | null Longitude, WGS 84. null when missing.

Response examples

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
        }
    ]
}

Error codes

Code	Slug	When it occurs
401	neautentificat	Token missing, invalid, expired or revoked.
403	feature_indisponibil	The current plan does not include the feature the route depends on.
422	validare	An undeclared parameter or a value that fails validation (`q`, `judet`, `nivel`, `tip`, `secundare`, `alias`, `limita`). The offending field is in `detalii`.
429	cota_depasita	The plan's monthly quota has been exceeded (see `Retry-After`).

All errors share the same shape. eroare.cod is stable and is the value you should branch on in code — not the text in mesaj, which may change.

{
    "eroare": {
        "cod": "validare",
        "mesaj": "An undeclared parameter or a value that fails validation (q, judet, nivel, tip, secundare, alias, limita). The offending field is in detalii.",
        "detalii": {
            "q": [
                "The value sent does not satisfy the parameter rule."
            ]
        }
    }
}