oneapi
Autentificare
Locations v1 / Ierarhie & dropdown-uri

Detaliu UAT

Un UAT după cod_siruta, cu județul părinte, reședința (chainable) și numărul de
localități. Expandabil cu ?include=localitati,populatie,secundare (secundare =
cătunele/cartierele din UAT). Fără geospatial / CUI (rute dedicate).

GET
https://oneapi.ro/api/locations/v1/uat/{cod}

Parametri de cale

NumeTipDescriereExemplu
codobligatoriu string Codul SIRUTA al unităţii administrativ-teritoriale (ex. 54975 pentru Cluj-Napoca).

Parametri de interogare

NumeTipDescriereValori acceptate
includelistăopțional text Secțiuni expandabile, separate prin virgulă. localitatipopulatiesecundare

Cum se comportă

  • Când resedinta e null, resedinta_nota spune de ce. Sunt trei cazuri, toate particularităţi reale ale organizării administrative, nu goluri de date: judeţul şi municipiul Bucureşti (care e el însuşi reşedinţă, iar la nivel de localitate are doar cele şase sectoare) şi judeţul Ilfov (a cărui reşedinţă, Bucureştiul, e în afara lui).
  • 227 din cele 13.755 de localităţi (1,65%) n-au cifră de populaţie — sate aproape depopulate, pentru care recensământul din 2021 n-a publicat o valoare (cea mai mică cifră publicată în ţară e 3). Nu e o legătură nefăcută: toate 227 există, cu geometrie şi cu identificator GeoNames. Cifrele de judeţ şi de UAT nu sunt afectate — vin din rândurile lor proprii de recensământ, nu din însumarea localităţilor. Cine însumează el localităţile pierde, la nivel naţional, 96 de persoane din 19.053.815.
  • {cod} e cod_siruta al UAT-ului.
  • Fără CUI și fără geospatial — pe rute dedicate (/uat/{cod}/primarie, /uat/{cod}/geometrie).
  • include=secundare (cătune/cartiere din OSM/GeoNames) are acoperire parțială și poate ieși gol pentru UAT-uri fără astfel de locuri cunoscute.
  • geoname_id și wikidata_qid sunt punți către alte seturi de date — cheia publică rămâne cod_siruta. Drumul invers (identificator extern → entitate) e la /referinte/{sursa}/{id}.

La ce folosește

  • Pagina de detaliu a unei comune / oraș cu județ, reședință și populație
  • Rezolvarea unui cod_siruta la UAT-ul complet pentru afișare și etichetare
  • Încărcarea localităților componente într-un singur call (include=localitati)

Structura răspunsului

CâmpTipDescriere
data.cod_siruta integer Codul SIRUTA (cheia publică a entității).
data.nume string Denumirea entității.
data.tip string Tipul entității (cod brut; denumirile la /nomenclatoare/tipuri).
data.mediu string | null urban sau rural (în bază e codul SIRUTA 1/3).
data.geoname_id integer | null Id-ul GeoNames al UAT-ului (punte externă, nu cheie de-a noastră).
data.wikidata_qid string | null QID-ul Wikidata al UAT-ului.
data.judet object Județul părinte (link în sus).
data.judet.cod string Indicativul auto al județului.
data.judet.nume string Numele județului.
data.resedinta object Reședința, chainable.
data.resedinta.nume string Denumirea localității de reședință.
data.resedinta.cod_siruta integer Codul SIRUTA al reședinței — chainable spre /localitati/{cod}.
data.resedinta_nota string | null De ce nu există reşedinţă. Apare doar când resedinta e null.
data.populatie integer | null Populația (recensământ).
data.suprafata_kmp number | null Suprafața, în km².
data.nr_localitati integer Câte localități are UAT-ul.
data.populatie_detaliu object Prezent doar cu include=populatie.
data.populatie_detaliu.masculin integer | null Populația masculină.
data.populatie_detaliu.feminin integer | null Populația feminină.
data.populatie_detaliu.an integer | null Anul recensământului sursă.
data.populatie_detaliu.sursa string | null Sursa populației (ex. RPL2021).
data.localitati[] array Prezent doar cu include=localitati.
data.localitati[].cod_siruta integer Codul SIRUTA al localității componente.
data.localitati[].nume string Denumirea localității componente.
data.localitati[].tip string Tipul localității componente.
data.localitati[].populatie integer | null Populația localității componente.
data.secundare[] array Cătune/cartiere din UAT (nume, tip, coordonate, distanță) — doar cu include=secundare.
data.secundare[].nume string Denumirea cătunului sau cartierului.
data.secundare[].tip string catun sau cartier.
data.secundare[].lat number | null Latitudinea locului secundar (WGS84).
data.secundare[].lng number | null Longitudinea locului secundar (WGS84).
data.secundare[].distanta_m integer | null Distanța până la localitatea-mamă, în metri.
data.secundare[].sursa string De unde vine locul secundar: osm sau geonames.
meta.actualizat object Prospețimea datelor pe domenii (dată ISO 8601).
meta.distanta object Cum sunt măsurate distanţele din răspuns. Apare pe orice răspuns care conţine o distanţă.
meta.distanta.metoda string Mereu linie_dreapta: distanţa geodezică pe suprafaţa Pământului, nu pe drum.
meta.distanta.detaliu string Aceeaşi informaţie, în cuvinte.

Exemple de răspuns

GEThttps://oneapi.ro/api/locations/v1/uat/54975
{
    "data": {
        "cod_siruta": 54975,
        "nume": "Cluj-Napoca",
        "tip": "municipiu",
        "mediu": "urban",
        "geoname_id": 681290,
        "wikidata_qid": "Q100188",
        "judet": {
            "cod": "CJ",
            "nume": "Cluj"
        },
        "resedinta": {
            "nume": "Cluj-Napoca",
            "cod_siruta": 54984
        },
        "resedinta_nota": null,
        "populatie": 286598,
        "suprafata_kmp": 174.8759,
        "nr_localitati": 1
    },
    "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.
404negasitUAT-ul nu există.
422validareUn parametru nu a trecut validarea (include); detalii spune care şi de ce.
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 nu a trecut validarea (include); detalii spune care şi de ce.",
        "detalii": {
            "cod": [
                "Valoarea trimisă nu respectă regula parametrului."
            ]
        }
    }
}