Locations v1 / Coduri poștale

Detaliu cod poștal

Reverse lookup: dintr-un cod poștal (6 cifre) → localitatea + ce acoperă codul
(strada + numere/blocuri, la nivel urban). Cod inexistent sau malformat → 404.

GET

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

Parametri de cale

NumeTipDescriereExemplu

codobligatoriu string Codul poştal, şase cifre.

Parametri de interogare

Ruta nu acceptă parametri de interogare.

Cum se comportă

Dintr-un cod → localitatea + ce acoperă codul. La nivel urban, codul e legat de o stradă și numere/blocuri (MFP).

La ce folosește

Autocompletare la checkout: userul tastează codul poștal, tu pre-completezi localitatea (și strada, la urban).
La retur/expediere: dintr-un cod de pe colet afli localitatea de destinație.
Normalizarea unei baze cu doar coduri poștale către localități oficiale, pentru raportare.

Structura răspunsului

CâmpTipDescriere

data.cod_postal string Codul poștal.

data.nivel string localitate (rural/general) | strada (urban).

data.localitate.cod_siruta integer Codul SIRUTA al localității — chainable spre /localitati/{cod}.

data.localitate.nume string Denumirea localității.

data.localitate.tip string Tipul localității.

data.localitate.judet.cod string Indicativul auto al județului.

data.localitate.judet.nume string Numele județului.

data.localitate.uat.cod_siruta integer Codul SIRUTA al UAT-ului — chainable spre /uat/{cod}.

data.localitate.uat.nume string Denumirea UAT-ului.

data.acoperire[] array Gol pentru coduri de nivel localitate.

data.acoperire[].strada string Strada acoperită de cod, aşa cum e denumită în nomenclator.

data.acoperire[].numere[].start integer | null Primul număr poștal din interval.

data.acoperire[].numere[].sfarsit integer | null Ultimul număr poștal din interval.

data.acoperire[].numere[].paritate string | null par | impar | null.

data.acoperire[].blocuri[] string Blocurile acoperite de cod, unde codul e dat pe bloc, nu pe număr.

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

Exemple de răspuns

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

{
    "data": {
        "cod_postal": "400001",
        "nivel": "strada",
        "localitate": {
            "cod_siruta": 54984,
            "nume": "Cluj-Napoca",
            "tip": "resedinta_municipiu",
            "judet": {
                "cod": "CJ",
                "nume": "Cluj"
            },
            "uat": {
                "cod_siruta": 54975,
                "nume": "Cluj-Napoca"
            }
        },
        "acoperire": [
            {
                "strada": "Moților",
                "numere": [
                    {
                        "start": 1,
                        "sfarsit": 39,
                        "paritate": "impar"
                    }
                ],
                "blocuri": [
                    "20-22",
                    "20-21",
                    "34-36",
                    "1-3",
                    "1A"
                ]
            }
        ]
    },
    "meta": {
        "actualizat": {
            "administrativ": "2026-08-15T16: 39: 14+03: 00",
            "adrese": "2026-10-04T19: 50: 09+03: 00"
        }
    }
}

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

{
    "data": {
        "cod_postal": "050506",
        "nivel": "strada",
        "localitate": {
            "cod_siruta": 179187,
            "nume": "București Sectorul 5",
            "tip": "sector",
            "judet": {
                "cod": "B",
                "nume": "București"
            },
            "uat": {
                "cod_siruta": 179132,
                "nume": "București"
            }
        },
        "acoperire": [
            {
                "strada": "Razoare",
                "numere": [
                    {
                        "start": 1,
                        "sfarsit": 9,
                        "paritate": "par"
                    }
                ],
                "blocuri": []
            }
        ]
    },
    "meta": {
        "actualizat": {
            "administrativ": "2026-08-15T16: 39: 14+03: 00",
            "adrese": "2026-10-04T19: 50: 09+03: 00"
        }
    }
}

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

{
    "data": {
        "cod_postal": "700001",
        "nivel": "strada",
        "localitate": {
            "cod_siruta": 95079,
            "nume": "Iași",
            "tip": "resedinta_municipiu",
            "judet": {
                "cod": "IS",
                "nume": "Iași"
            },
            "uat": {
                "cod_siruta": 95060,
                "nume": "Iași"
            }
        },
        "acoperire": [
            {
                "strada": "Străpungere Silvestru",
                "numere": [
                    {
                        "start": 1,
                        "sfarsit": 7,
                        "paritate": "impar"
                    }
                ],
                "blocuri": []
            }
        ]
    },
    "meta": {
        "actualizat": {
            "administrativ": "2026-08-15T16: 39: 14+03: 00",
            "adrese": "2026-10-04T19: 50: 09+03: 00"
        }
    }
}

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	Cod inexistent sau malformat.
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": "Cod inexistent sau malformat."
    }
}