Locations v1 / Coduri poștale

Postcode detail

Reverse lookup: from a postal code (six digits) → the locality plus what the code covers (the street and its house numbers or blocks, in urban areas). A non-existent or malformed code → 404.

GET

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

Path parameters

NameTypeDescriptionExample

codrequired string Postal code, six digits.

Query parameters

This route accepts no query parameters.

How it behaves

From a code → the locality plus what the code covers. In urban areas the code is tied to a street and to house numbers or blocks (Ministry of Finance data).

What it is for

Autocomplete at checkout: the user types the postal code, you prefill the locality (and the street, in urban areas).
Returns and shipping: from a code on a parcel you get the destination locality.
Normalising a database that holds only postal codes into official localities, for reporting.

Response structure

FieldTypeDescription

data.cod_postal string The postal code.

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

data.localitate.cod_siruta integer The locality's SIRUTA code — chainable to /localitati/{cod}.

data.localitate.nume string The name of the locality.

data.localitate.tip string The type of locality.

data.localitate.judet.cod string The county's registration prefix.

data.localitate.judet.nume string The name of the county.

data.localitate.uat.cod_siruta integer The SIRUTA code of the administrative unit — chainable to /uat/{cod}.

data.localitate.uat.nume string The name of the administrative unit.

data.acoperire[] array Empty for locality-level codes.

data.acoperire[].strada string The street covered by the code, as named in the nomenclature.

data.acoperire[].numere[].start integer | null The first house number in the range.

data.acoperire[].numere[].sfarsit integer | null The last house number in the range.

data.acoperire[].blocuri[] string The blocks covered by the code, where the code is assigned per block rather than per number.

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

Response examples

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

Error codes

Code	Slug	When it occurs
401	neautentificat	Token missing, invalid, expired or revoked.
403	feature_indisponibil	The current plan does not include the feature the route depends on.
404	negasit	The code does not exist or is malformed.
429	cota_depasita	The 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": "negasit",
        "mesaj": "The code does not exist or is malformed."
    }
}