Locations v1 / Coduri poștale

Codurile poștale ale unei localități

Lista paginată a codurilor poștale ale unei localități (identificată prin cod_siruta),
fiecare cu strada acoperită (null la nivel localitate).

GET

https://oneapi.ro/api/locations/v1/localitati/{cod}/coduri-postale

Parametri de cale

NumeTipDescriereExemplu

codobligatoriu string Codul SIRUTA al localităţii (ex. 54984).

Parametri de interogare

Ruta nu acceptă parametri de interogare.

Cum se comportă

Urban = multe coduri (per stradă), rural = unul singur. De aceea e paginat.

La ce folosește

Sugerezi codurile poștale valide după ce userul a ales localitatea (dropdown de cod la urban).
Validare inversă: verifici că un cod introdus aparține localității selectate.
Construiești maparea stradă → cod pentru o localitate urbană, pentru etichete de livrare.

Structura răspunsului

CâmpTipDescriere

data[].cod_postal string Codul poștal.

data[].strada string | null Strada acoperită (null la nivel localitate).

data[].nivel string La ce se aplică codul: localitate întreagă sau stradă.

meta.paginare.pagina integer Pagina curentă.

meta.paginare.per_pagina integer Rezultate pe pagină.

meta.paginare.total integer Total rezultate.

meta.paginare.pagini integer Număr de pagini.

meta.actualizat object Prospețimea datelor pe domenii (dată ISO 8601).

Exemple de răspuns

GEThttps://oneapi.ro/api/locations/v1/localitati/54984/coduri-postale

{
    "data": [
        {
            "cod_postal": "400326",
            "strada": "1 Decembrie 1918",
            "nivel": "strada"
        }
    ],
    "meta": {
        "actualizat": {
            "administrativ": "2026-08-15T16: 39: 14+03: 00",
            "adrese": "2026-10-04T19: 50: 09+03: 00"
        },
        "paginare": {
            "pagina": 1,
            "per_pagina": 20,
            "total": 218,
            "pagini": 11
        }
    }
}

GEThttps://oneapi.ro/api/locations/v1/localitati/179196/coduri-postale

{
    "data": [
        {
            "cod_postal": "061621",
            "strada": "1 Mai",
            "nivel": "strada"
        }
    ],
    "meta": {
        "actualizat": {
            "administrativ": "2026-08-15T16: 39: 14+03: 00",
            "adrese": "2026-10-04T19: 50: 09+03: 00"
        },
        "paginare": {
            "pagina": 1,
            "per_pagina": 20,
            "total": 1069,
            "pagini": 54
        }
    }
}

GEThttps://oneapi.ro/api/locations/v1/localitati/155252/coduri-postale

{
    "data": [
        {
            "cod_postal": "300172",
            "strada": "16 Decembrie 1989",
            "nivel": "strada"
        }
    ],
    "meta": {
        "actualizat": {
            "administrativ": "2026-08-15T16: 39: 14+03: 00",
            "adrese": "2026-10-04T19: 50: 09+03: 00"
        },
        "paginare": {
            "pagina": 1,
            "per_pagina": 20,
            "total": 1044,
            "pagini": 53
        }
    }
}

GEThttps://oneapi.ro/api/locations/v1/localitati/8176/coduri-postale

{
    "data": [
        {
            "cod_postal": "517786",
            "strada": null,
            "nivel": "localitate"
        }
    ],
    "meta": {
        "actualizat": {
            "administrativ": "2026-08-15T16: 39: 14+03: 00",
            "adrese": "2026-10-04T19: 50: 09+03: 00"
        },
        "paginare": {
            "pagina": 1,
            "per_pagina": 20,
            "total": 1,
            "pagini": 1
        }
    }
}

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.
404	negasit	Localitatea nu există.
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": "negasit",
        "mesaj": "Localitatea nu există."
    }
}