Utile v1 / Adrese

Subdiviziuni poștale

Subdiviziunile pe care serviciile poştale ale unei ţări le aşteaptă în adresă — state, provincii, judeţe — cu cheia de trimis şi eticheta de afişat.

GET

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

Parametri de cale

NumeTipDescriereExemplu

taraobligatoriu string Codul ISO 3166-1 alpha-2 al ţării (ex. US).

Parametri de interogare

Ruta nu acceptă parametri de interogare.

Cum se comportă

Lista e cea folosită de sursă la validarea adreselor, nu neapărat ISO 3166-2. cod apare doar unde sursa îl declară — la unele țări e chiar codul ISO, la altele lipsește.
cod_postal_prefix există la țările unde codul poștal codifică regiunea (SUA, Japonia). E o expresie regulată, nu un prefix literal: 3[56] înseamnă că orice cod care începe cu 35 sau 36 e din Alabama.
O listă goală înseamnă că sursa n-are subdiviziuni pentru țara aia — fie n-au relevanță poștală, fie nu le publică. Nu e o eroare.

La ce folosește

Populezi lista de state/județe din formularul de adresă, în ordinea și forma folosite de poșta țării.
Verifici dacă valoarea primită într-un import de date e o subdiviziune reală.
Afli prefixul de cod poștal al unui stat, unde sursa îl publică.

Structura răspunsului

Toate câmpurile de mai jos sunt în data.

CâmpTipDescriere

tara string Ţara la care se referă valoarea.

eticheta string Cum se numesc local subdiviziunile (state, county, province).

inregistrari integer Câte înregistrări are răspunsul.

subdiviziuni[].cheie string Cheia sursei — de obicei chiar numele.

subdiviziuni[].nume string Numele afișabil.

subdiviziuni[].cod string Codul, unde sursa îl declară.

subdiviziuni[].cod_postal_prefix string Expresia regulată a codurilor poștale din subdiviziune, unde există.

observatie string Precizare despre cum se citeşte răspunsul: o convenţie de calcul sau o limită a datelor.

sursa.nume string Denumirea sursei oficiale.

sursa.licenta string Licenţa sub care sursa permite reutilizarea.

subdiviziuni[].latin Forma latină a numelui, la țările cu alt alfabet.

Exemple de răspuns

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

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	Nu avem date de adresare pentru codul dat.
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": "Nu avem date de adresare pentru codul dat."
    }
}