Utile v1 / Adrese

Postal subdivisions

The subdivisions a country's postal service expects in an address — states, provinces, counties — with the key to send and the label to display.

GET

https://oneapi.ro/api/utile/v1/adrese/{tara}/subdiviziuni

Path parameters

NameTypeDescriptionExample

tararequired string ISO 3166-1 alpha-2 country code (e.g. US).

Query parameters

This route accepts no query parameters.

How it behaves

The list is the one the source uses for address validation, not necessarily ISO 3166-2. cod appears only where the source declares it — for some countries it is the ISO code, for others it is absent.
cod_postal_prefix exists for countries whose postal code encodes the region (US, Japan). It is a regular expression, not a literal prefix: 3[56] means any code starting with 35 or 36 is in Alabama.
An empty list means the source has no subdivisions for that country — either they carry no postal relevance, or it does not publish them. It is not an error.

What it is for

Populate the state/county list in an address form, in the order and form the country's post office uses.
Check whether a value received in a data import is a real subdivision.
Find a state's postal-code prefix, where the source publishes one.

Response structure

All fields below live inside data.

FieldTypeDescription

tara string The country the value refers to.

eticheta string What subdivisions are called locally (state, county, province).

inregistrari integer How many records the response holds.

subdiviziuni[].cheie string The source key — usually the name itself.

subdiviziuni[].nume string The display name.

subdiviziuni[].cod string The code, where the source declares one.

subdiviziuni[].cod_postal_prefix string Regular expression of the postal codes in that subdivision, where one exists.

observatie string A note on how to read the response: a computation convention or a limit of the data.

sursa.nume string Name of the official source.

sursa.licenta string The licence under which the source allows reuse.

subdiviziuni[].latin The Latin form of the name, for countries using another script.

Response examples

GEThttps://oneapi.ro/api/utile/v1/adrese/US/subdiviziuni

{
    "data": {
        "tara": "US",
        "eticheta": "state",
        "inregistrari": 62,
        "subdiviziuni": [
            {
                "cheie": "AL",
                "nume": "Alabama",
                "cod": "AL",
                "cod_postal_prefix": "3[56]"
            }
        ],
        "observatie": "Lista e cea folosită de sursă la validarea adreselor; `cod` e prezent doar unde sursa îl declară (nu peste tot e ISO 3166-2).",
        "sursa": {
            "nume": "Google libaddressinput — metadatele de adresare folosite de Chrome",
            "licenta": "Apache-2.0."
        }
    }
}

GEThttps://oneapi.ro/api/utile/v1/adrese/RO/subdiviziuni

{
    "data": {
        "tara": "RO",
        "eticheta": null,
        "inregistrari": 42,
        "subdiviziuni": [
            {
                "cheie": "Alba",
                "nume": "Alba",
                "cod": "AB"
            }
        ],
        "observatie": "Lista e cea folosită de sursă la validarea adreselor; `cod` e prezent doar unde sursa îl declară (nu peste tot e ISO 3166-2).",
        "sursa": {
            "nume": "Google libaddressinput — metadatele de adresare folosite de Chrome",
            "licenta": "Apache-2.0."
        }
    }
}

GEThttps://oneapi.ro/api/utile/v1/adrese/DE/subdiviziuni

{
    "data": {
        "tara": "DE",
        "eticheta": null,
        "inregistrari": 0,
        "subdiviziuni": [],
        "observatie": "Sursa nu are subdiviziuni pentru țara asta — fie n-are relevanță poștală, fie nu le publică.",
        "sursa": {
            "nume": "Google libaddressinput — metadatele de adresare folosite de Chrome",
            "licenta": "Apache-2.0."
        }
    }
}

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	We hold no addressing data for the given code.
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": "We hold no addressing data for the given code."
    }
}