oneapi
Autentificare
Locations v1 / Demografie

Clasament

Top localități, UAT-uri sau județe după un criteriu. nivel alege entitatea, dupa alege
criteriul (implicit populația), judet restrânge, limita = câte (implicit 20).

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

Parametri de interogare

NumeTipDescriereValori acceptate
nivelobligatoriu string Entitatea clasată. localitateuatjudet
dupaopțional string | null Criteriul de clasare. populatiesuprafatadensitatefirmedensitate_firme
judetopțional string | null Restrânge la un județ (cod_auto). ex. CJ
limitaopțional integer | null Câte rezultate. 201 – 100

Cum se comportă

  • Top localități, UAT-uri sau județe după criteriul din dupa (implicit populația), opțional restrâns la un județ.
  • Criteriile disponibile depind de nivel, iar limita e a datelor, nu a rutei: densitate și densitate_firme nu există la localitate, fiindcă localitățile n-au suprafață în nomenclator (o au doar UAT-urile și județele). O densitate fără numitor ar fi o cifră inventată — de aceea răspunsul e 422 cu lista criteriilor posibile pentru nivelul cerut, nu o valoare aproximativă.
  • Entitățile fără valoare pe criteriul cerut se exclud, nu se clasează cu zero: o localitate fără nicio firmă nu apare în topul după firme, dar nici nu figurează ca „ultima, cu 0".
  • valoare e mărimea după care s-a făcut clasarea, iar criteriu și um din antetul răspunsului spun care e și în ce se măsoară. populatie rămâne în fiecare rând ca reper, chiar când clasarea e după altceva.

La ce folosește

  • Widget „top orașe după populație” într-un dashboard sau pagină publică.
  • Prioritizarea piețelor: ordonezi UAT-urile unui județ după populație pentru expansiune.
  • Popularea unui dropdown „cele mai mari localități” pentru selecție rapidă.

Structura răspunsului

CâmpTipDescriere
data[].pozitie integer Rangul în clasament (1 = cea mai mare valoare).
data[].cod string Cheia cu care se continuă spre ruta de detaliu a nivelului: cod auto la județ, cod SIRUTA la UAT și localitate.
data[].cod_siruta integer Codul SIRUTA al entității — prezent la toate nivelurile, ca forma să nu difere.
data[].nume string Denumirea entității.
data[].tip string | null Tipul entității clasate (municipiu/oraș/comună sau tip localitate); null la județ.
data[].judet.cod string Indicativul auto al județului entității.
data[].judet.nume string Numele județului entității.
data[].populatie integer | null Populația entității — reper, indiferent de criteriu.
data[].valoare number Valoarea după care s-a făcut clasarea, în unitatea din um.
meta.actualizat object Prospețimea datelor pe domenii (dată ISO 8601).

Exemple de răspuns

GEThttps://oneapi.ro/api/locations/v1/clasament?nivel=uat&judet=CJ&limita=5
{
    "data": [
        {
            "pozitie": 1,
            "cod": "54975",
            "cod_siruta": 54975,
            "nume": "Cluj-Napoca",
            "tip": "municipiu",
            "judet": {
                "cod": "CJ",
                "nume": "Cluj"
            },
            "populatie": 286598,
            "valoare": 286598
        }
    ],
    "meta": {
        "criteriu": "populatie",
        "um": "locuitori",
        "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_invalizinivel lipsă sau invalid.
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": "nivel lipsă sau invalid.",
        "detalii": {
            "nivel": [
                "Valoarea trimisă nu respectă regula parametrului."
            ]
        }
    }
}