oneapi
Sign in
Locations v1 / Căutare & rezolvare

Search places (gazetteer)

A unified search across counties, administrative units and localities plus their alternative names, and across secondary places (hamlets and neighbourhoods). The latter can be excluded with ?secundare=0. The response also carries the actualizat meta (data freshness).

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

Query parameters

NameTypeDescriptionAccepted values
qoptional string | null The prefix searched for, across names and alternative names. Without it, the route returns the first entities in the default order. max 100 car.
judetoptional string | null The county's vehicle registration prefix (CJ, IF, B) — the one your user knows, not the SIRUTA code. e.g. SV
niveloptional string | null Administrative level: uat or localitate. uatlocalitate
tipoptional string | null Unit type (municipiu, oras, comuna, sat…). The full names are at /nomenclatoare/tipuri. max 30 car.
secundareoptional boolean | null Include hamlets and neighbourhoods. On by default at /cauta; 0 excludes them. e.g. 0
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

  • Searches across counties, administrative units (UAT) and localities, plus their alternative names (exonyms, historical names).
  • Cascade: prefix → substring → fuzzy. With or without diacritics makes no difference — everything is normalised server-side.
  • When the match came from an alternative name, potrivit_ca appears — show it, or the user will not understand why „Kolozsvár" returned Cluj-Napoca.
  • Secondary places are included too — hamlets and neighbourhoods (nivel = catun/cartier), with no SIRUTA code, anchored to their parent unit in parte_din. They rank below official localities, so they appear at the end. Exclude them with ?secundare=0.

What it is for

  • General place search in a portal: the user looks for a town or village and you get back the official entity with coordinates and population.
  • Cleaning up an import with freely typed place names (Hungarian and German exonyms included) into official entities, via the alternative names.
  • Fine-grained address search when you want hamlets and neighbourhoods in the results, not just the official units.

Response structure

FieldTypeDescription
data[].cod_siruta integer The entity's public key (locality/administrative unit). null for counties and for secondary places (hamlets/neighbourhoods).
data[].nume string The name of the entity.
data[].nume_afisare string Disambiguated name for homonyms („Baia (Suceava)").
data[].nume_ascii string The name without diacritics — the form matching runs against.
data[].nivel string uat | localitate | catun | cartier.
data[].tip string Entity type (raw code; the full names are at /nomenclatoare/tipuri).
data[].populatie integer Population (census).
data[].judet string The name of the entity's county.
data[].judet_cod string The county's vehicle registration prefix („CJ").
data[].uat null The name of the entity's administrative unit.
data[].lat number Latitude, WGS 84 (the seat for an administrative unit, the place's own point otherwise). null when missing.
data[].lng number Longitude, WGS 84. null when missing.
data[].parte_din object | null Present only for secondary places: the parent administrative unit the hamlet or neighbourhood is anchored to.
data[].potrivit_ca object | null Present only when the match came from an alternative name.
meta.actualizat.administrativ string When this particular data set was last refreshed.
meta.actualizat.populatie string When this particular data set was last refreshed.
data[].parte_din.uat The administrative unit the secondary place (hamlet/neighbourhood) belongs to.
data[].potrivit_ca.nume The name form that produced the match — it may be an alias, not the canonical name.
data[].potrivit_ca.tip What kind of name matched: exonym, historical name, variant.
data[].potrivit_ca.lang The language of the matched alias, where known.
data[].potrivit_ca.sursa Where the alias comes from (official nomenclature, OSM, Wikidata).
data[].potrivit_ca.valabil_pana_la The year the name stopped being official, for historical names.
data[].cod_postal The postal code, where the entity has exactly one.

Response examples

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

Error codes

CodeSlugWhen it occurs
401neautentificatToken missing, invalid, expired or revoked.
403feature_indisponibilThe current plan does not include the feature the route depends on.
422validareAn undeclared parameter or a value that fails validation (q, judet, nivel, tip, secundare, alias, limita). The offending field is in detalii.
429cota_depasitaThe 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."
            ]
        }
    }
}