Locations v1 / Validare adrese

Validează adresă

⭐ Verifică coerența unei adrese (județ / localitate / stradă / cod poștal) și întoarce
validitatea per componentă + corecții sugerate. Potrivire după nume (exact, apoi fuzzy).

GET

https://oneapi.ro/api/locations/v1/validare/adresa

Parametri de interogare

NumeTipDescriereValori acceptate

judetopțional text Maxim 100. max 100 car.

localitateobligatoriu text Maxim 150. max 150 car.

stradaopțional text Maxim 200. max 200 car.

cod_postalopțional text Maxim 10. max 10 car.

Cum se comportă

Verifică o adresă (județ/localitate/stradă/cod poștal) și întoarce validitatea per componentă + corecții.
Potrivire după nume: exact, apoi fuzzy pentru sugestii. Nu implică geometrie de străzi.

La ce folosește

Checkout de ecommerce cu dropdown-uri: validezi că județul/localitatea/strada/codul poștal se potrivesc înainte de a plasa comanda; la cod greșit întorci codurile corecte.
Emitere de facturi: verifici coerența adresei fiscale înainte de a genera documentul.
Curățarea unei baze de clienți: treci lista prin validare și aplici corecțiile sugerate în masă.

Structura răspunsului

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

CâmpTipDescriere

valid boolean Adresa e coerentă în întregime.

componente object Câte un obiect {valid, …} per componentă trimisă.

componente.judet.valid boolean Județul a fost recunoscut în nomenclator.

componente.localitate.valid boolean Localitatea a fost recunoscută, în județul dat.

componente.localitate.sugestie string Cea mai apropiată localitate, la nepotrivire.

componente.strada.valid boolean Strada a fost recunoscută, în localitatea dată.

componente.cod_postal.valid boolean Codul poștal e coerent cu restul adresei.

componente.cod_postal.asteptat[] string Codurile corecte, la nepotrivire.

corectii[] string Mesaje lizibile cu ce nu se potrivește și ce sugerăm.

Exemple de răspuns

GEThttps://oneapi.ro/api/locations/v1/validare/adresa?judet=CJ&localitate=Cluj-Napoca&strada=Moților&cod_postal=400001

{
    "data": {
        "valid": true,
        "componente": {
            "judet": {
                "valid": true,
                "cod": "CJ",
                "nume": "Cluj"
            },
            "localitate": {
                "valid": true,
                "cod_siruta": 54984,
                "nume": "Cluj-Napoca"
            },
            "strada": {
                "valid": true,
                "nume": "Moților"
            },
            "cod_postal": {
                "valid": true,
                "cod": "400001"
            }
        },
        "corectii": []
    },
    "meta": {
        "actualizat": {
            "administrativ": "2026-08-15T16: 39: 14+03: 00",
            "adrese": "2026-10-04T19: 50: 09+03: 00"
        }
    }
}

Întoarce codurile corecte în asteptat.

GEThttps://oneapi.ro/api/locations/v1/validare/adresa?localitate=Cluj-Napoca&strada=Moților&cod_postal=400999

{
    "data": {
        "valid": false,
        "componente": {
            "localitate": {
                "valid": true,
                "cod_siruta": 54984,
                "nume": "Cluj-Napoca"
            },
            "strada": {
                "valid": true,
                "nume": "Moților"
            },
            "cod_postal": {
                "valid": false,
                "primit": "400999",
                "asteptat": [
                    "400001",
                    "400003",
                    "400370"
                ]
            }
        },
        "corectii": [
            "Codul poștal 400999 nu corespunde străzii Moților."
        ]
    },
    "meta": {
        "actualizat": {
            "administrativ": "2026-08-15T16: 39: 14+03: 00",
            "adrese": "2026-10-04T19: 50: 09+03: 00"
        }
    }
}

GEThttps://oneapi.ro/api/locations/v1/validare/adresa?localitate=54984

{
    "data": {
        "valid": false,
        "componente": {
            "localitate": {
                "valid": false,
                "primit": "54984"
            }
        },
        "corectii": [
            "Localitatea „54984” nu a fost găsită."
        ]
    },
    "meta": {
        "actualizat": {
            "administrativ": "2026-08-15T16: 39: 14+03: 00",
            "adrese": "2026-10-04T19: 50: 09+03: 00"
        }
    }
}

GEThttps://oneapi.ro/api/locations/v1/validare/adresa?localitate=54984&judet=CJ

{
    "data": {
        "valid": false,
        "componente": {
            "judet": {
                "valid": true,
                "cod": "CJ",
                "nume": "Cluj"
            },
            "localitate": {
                "valid": false,
                "primit": "54984"
            }
        },
        "corectii": [
            "Localitatea „54984” nu a fost găsită în județul Cluj."
        ]
    },
    "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.
422	parametri_invalizi	`localitate` lipsește.
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": "parametri_invalizi",
        "mesaj": "localitate lipsește.",
        "detalii": {
            "judet": [
                "Valoarea trimisă nu respectă regula parametrului."
            ]
        }
    }
}