oneapi
Autentificare
Locations v1 / Validare adrese

Parsează adresă (text liber)

Primește un singur string (q) — ex. „Petroșani, jud Hunedoara, str Șt O Iosif nr 1a" —
* îl parsează în componente și le potrivește conjunctiv: fiecare semnal (județ / stradă /
* cod poștal / număr) restrânge rezultatul, iar dacă totul duce la o singură entitate se
* întoarce doar aceea. Fără boolean „valid": nivel_confirmat spune cât de adânc s-a
confirmat, componente[*].stare ce s-a întâmplat cu fiecare câmp, potrivire un rezumat.
Datele oficiale (localitate→UAT→județ→regiune, cod poștal) sunt complete; strada/numărul
vin din OSM (acoperire parțială), deci pot ieși negasit fără ca adresa să fie invalidă.

GET
https://oneapi.ro/api/locations/v1/validare/parsare

Parametri de interogare

NumeTipDescriereValori acceptate
qopțional string | null Adresa ca text liber (ex. „Strada Memorandumului 28, Cluj-Napoca, Cluj"). max 255 car.

Cum se comportă

  • Parsează o adresă ca text liber (q) în componente și le potrivește conjunctiv: fiecare semnal (județ / localitate / stradă / cod poștal / număr) restrânge rezultatul; dacă totul duce la o singură entitate, se întoarce doar aceea.
  • Fără boolean „valid": nivel_confirmat spune cât de adânc s-a confirmat, componente[*].stare ce s-a întâmplat cu fiecare câmp, potrivire un rezumat.
  • Oficialul (localitate→UAT→județ→regiune, cod poștal) e complet; strada/numărul vin din OSM (acoperire parțială), deci pot ieși negasit fără ca adresa să fie invalidă.
  • Potrivirea folosește gazetteer-ul (aliasuri: „Cluj" → Cluj-Napoca, exonime, denumiri istorice) și dezambiguizează pe populație. rezultate[].matched_on spune CUM s-a potrivit fiecare entitate.
  • unparsed conține segmentele pe care nu le-am putut asigna (ex. „lângă biserică") — obligatoriu, chiar și gol; e sursa principală de îmbunătățiri (aliasuri lipsă etc.).

La ce folosește

  • O singură casetă „adresă completă": userul lipește tot, tu spargi în componente și rezolvi la localitate/UAT/județ (geocodare administrativă) cu cod_siruta.
  • Procesare de comenzi din emailuri/CSV/marketplace: adrese în text liber → entități oficiale, pentru rutare la curier sau raportare pe județ.
  • Confirmare pentru user: din ce a tastat, îi arăți ce a înțeles sistemul („am găsit Cluj-Napoca, jud. Cluj") înainte de a salva.

Structura răspunsului

CâmpTipDescriere
data.parsat object Componentele extrase din text: judet, localitate, strada, numar, cod_postal, detalii.
data.potrivire string exacta | partiala | niciuna — rezumatul potrivirii.
data.nivel_confirmat string Cât de adânc s-a confirmat: judet | localitate | strada | numar (sau null).
data.ambiguu boolean true dacă rămân mai multe entități posibile.
data.unparsed array Segmente din q neasignate niciunei componente („lângă biserică"). Prezent chiar și gol; sursă de îmbunătățiri.
data.componente object Câte un obiect {stare, …} per câmp trimis (stare: confirmat | negasit …; strada aduce sugestie/nota).
data.rezultate[].localitate object Localitatea potrivită (cod_siruta, nume, tip, populatie, lat, lng).
data.rezultate[].uat object UAT-ul părinte (cod_siruta, nume, tip).
data.rezultate[].judet object Județul (cod, nume).
data.rezultate[].regiune object Regiunea (cod, nume).
data.rezultate[].matched_on object Cum s-a potrivit fiecare entitate: nume_oficial | nume_scurt/exonim/denumire_istorica (alias) | fuzzy | cod_postal | inferat.
data.parsat.judet string Județul extras din text, sau null dacă n-a fost recunoscut.
data.parsat.localitate string Localitatea extrasă.
data.parsat.strada string Strada extrasă, fără tipul ei (Str., Bd.).
data.parsat.numar string Numărul poștal extras.
data.parsat.cod_postal null Codul poștal extras.
data.parsat.detalii null Restul: bloc, scară, etaj, apartament.
data.componente.*.stare Per câmp: dacă a fost găsit, confirmat în nomenclator sau doar presupus.
data.rezultate[].numar object Numărul poștal potrivit, cu codul poștal și coordonatele lui.
data.rezultate[].strada object Strada potrivită, cu cod poștal și coordonate.
meta.actualizat object Când au fost actualizate ultima dată nomenclatorul administrativ și cel de străzi.

Exemple de răspuns

GEThttps://oneapi.ro/api/locations/v1/validare/parsare?q=Strada%20Memorandumului%2028,%20Cluj-Napoca,%20Cluj
{
    "data": {
        "parsat": {
            "judet": "Cluj",
            "localitate": "Cluj-Napoca",
            "strada": "Memorandumului",
            "numar": "28",
            "cod_postal": null,
            "detalii": null
        },
        "potrivire": "exacta",
        "nivel_confirmat": "numar",
        "ambiguu": false,
        "unparsed": [],
        "componente": {
            "judet": {
                "stare": "confirmat",
                "cod": "CJ",
                "nume": "Cluj"
            },
            "localitate": {
                "stare": "confirmat"
            },
            "strada": {
                "stare": "confirmat",
                "nume": "Memorandumului"
            },
            "numar": {
                "stare": "confirmat",
                "numar": "28"
            }
        },
        "rezultate": [
            {
                "numar": {
                    "numar": "28",
                    "cod_postal": "400114",
                    "lat": 46.769304853413416,
                    "lng": 23.585544611959204
                },
                "strada": {
                    "nume": "Memorandumului",
                    "cod_postal": "400114",
                    "lat": 46.76951318182015,
                    "lng": 23.58672888056244
                },
                "localitate": {
                    "cod_siruta": 54984,
                    "nume": "Cluj-Napoca",
                    "tip": "resedinta_municipiu",
                    "populatie": 286598,
                    "lat": 46.78,
                    "lng": 23.559444444444
                },
                "uat": {
                    "cod_siruta": 54975,
                    "nume": "Cluj-Napoca",
                    "tip": "municipiu"
                },
                "judet": {
                    "cod": "CJ",
                    "nume": "Cluj"
                },
                "regiune": {
                    "cod": "RO11",
                    "nume": "Nord-Vest"
                },
                "matched_on": {
                    "localitate": "nume_oficial",
                    "strada": "nume_oficial"
                }
            }
        ]
    },
    "meta": {
        "actualizat": {
            "administrativ": "2026-08-15T16: 39: 14+03: 00",
            "strazi": "2026-10-06T16: 33: 40+03: 00"
        }
    }
}

Coduri de eroare

CodSlugCând apare
401neautentificatToken lipsă, invalid, expirat sau revocat.
403feature_indisponibilPlanul curent nu include funcţia de care ţine ruta.
422validareUn parametru nedeclarat ori o valoare care nu trece validarea (q). Câmpul vinovat e în detalii.
429cota_depasitaCota 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": "validare",
        "mesaj": "Un parametru nedeclarat ori o valoare care nu trece validarea (q). Câmpul vinovat e în detalii.",
        "detalii": {
            "q": [
                "Valoarea trimisă nu respectă regula parametrului."
            ]
        }
    }
}