oneapi
Sign in
Utile v1 / Adrese

Postal format

How an address is written in a country: the order of the lines, which fields are required, what the subdivision is called locally. For forms that do not assume the Romanian shape.

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

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 format template is kept RAW, exactly as the source gives it: %N name, %O organisation, %A street, %C locality, %S region, %Z postal code, %n newline. The campuri field translates it, so you need not parse the letters yourself.
  • 54 of the 252 countries declare no template of their own and receive the source default. For those, format_implicit is true — that is not missing data, it is the source's documented behaviour.
  • 70 countries have no postal codes at all (Angola, Hong Kong, Panama). For them cod_postal.exista is false, which is information rather than a gap: it means you should not ask for a code in the form.
  • Local labels matter in interfaces. A form asking a Briton for "State" or a Romanian for "ZIP" looks badly translated, even though every field is correct.

What it is for

  • Generate the checkout address form dynamically, with the fields in the right order for the chosen country.
  • Find out whether the country uses postal codes and what they look like, to validate before submission.
  • Label the region field correctly: "state" in the US, "county" in the UK, "județ" in Romania.

Response structure

All fields below live inside data.

FieldTypeDescription
tara string The country the value refers to.
nume string The name, exactly as the source publishes it.
format string The raw field-layout template.
format_implicit boolean true if the country declares no template of its own and the default was applied.
format_local null
campuri[] array The template translated: each field with its key, letter, description and whether it is required.
campuri[].cheie string
campuri[].litera string
campuri[].descriere string Plain-language explanation of the value.
campuri[].obligatoriu boolean
obligatorii array Keys of the fields without which the address is incomplete in this country.
majuscule array The fields the country's post office wants in upper case.
cod_postal.exista boolean Whether the country uses postal codes.
cod_postal.regex string The code pattern, without anchors — add them yourself if you use it directly.
cod_postal.exemple array Real codes, useful as form placeholders.
cod_postal.eticheta_locala null What the code is called locally (zip, postal, pin).
etichete_locale array Local names for the region, locality and sub-locality fields.
url_posta string The official postal-code lookup page, where the source knows one.
are_subdiviziuni boolean Whether the country has a list of postally recognised subdivisions.
observatie null 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.

Response examples

GEThttps://oneapi.ro/api/utile/v1/adrese/RO
{
    "data": {
        "tara": "RO",
        "nume": "România",
        "format": "%N%n%O%n%A%n%Z %S %C",
        "format_implicit": false,
        "format_local": null,
        "campuri": [
            {
                "cheie": "nume",
                "litera": "N",
                "descriere": "numele destinatarului",
                "obligatoriu": false
            }
        ],
        "obligatorii": [
            "strada",
            "localitate",
            "cod_postal"
        ],
        "majuscule": [
            "strada",
            "localitate"
        ],
        "cod_postal": {
            "exista": true,
            "regex": "\\d{6}",
            "exemple": [
                "060274",
                "061357",
                "200716"
            ],
            "eticheta_locala": null
        },
        "etichete_locale": [],
        "url_posta": "http://www.posta-romana.ro/zip_codes",
        "are_subdiviziuni": true,
        "observatie": null,
        "sursa": {
            "nume": "Google libaddressinput — metadatele de adresare folosite de Chrome",
            "licenta": "Apache-2.0."
        }
    }
}

Error codes

CodeSlugWhen it occurs
401neautentificatToken missing, invalid, expired or revoked.
403feature_indisponibilThe current plan does not include the feature the route depends on.
404negasitWe hold no addressing rules for the given code.
429cota_depasitaThe 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 rules for the given code."
    }
}