oneapi
Sign in
Locations v1 / Validare adrese

Parse an address (free text)

Takes a single string (q) — e.g. „Petroșani, jud Hunedoara, str Șt O Iosif nr 1a" — parses it into components and matches them conjunctively: every signal (county / street / postal code / number) narrows the result, and if everything points at a single entity only that one comes back. No „valid" boolean: nivel_confirmat says how deep the confirmation went, componente[*].stare what happened to each field, potrivire gives the summary. The official layer (locality→unit→county→region, postal code) is complete; street and number come from OSM (partial coverage), so they can come back negasit without the address being invalid.

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

Query parameters

NameTypeDescriptionAccepted values
qoptional string | null The address as free text (e.g. „Strada Memorandumului 28, Cluj-Napoca, Cluj"). max 255 car.

How it behaves

  • Parses an address given as free text (q) into components and matches them conjunctively: every signal (county / locality / street / postal code / number) narrows the result; if everything points at a single entity, only that one comes back.
  • No „valid" boolean: nivel_confirmat says how deep the confirmation went, componente[*].stare what happened to each field, potrivire gives the summary.
  • The official layer (locality→unit→county→region, postal code) is complete; street and number come from OSM (partial coverage), so they can come back negasit without the address being invalid.
  • Matching uses the gazetteer (aliases: „Cluj" → Cluj-Napoca, exonyms, historical names) and disambiguates by population. rezultate[].matched_on says HOW each entity was matched.
  • unparsed holds the segments we could not assign (e.g. „next to the church") — always present, even when empty; it is the main source of improvements (missing aliases and so on).

What it is for

  • A single „full address" box: the user pastes everything, you split it into components and resolve it to locality/unit/county (administrative geocoding) with a cod_siruta.
  • Processing orders from emails, CSVs or marketplaces: free-text addresses → official entities, for courier routing or county-level reporting.
  • Confirmation for the user: from what they typed, you show what the system understood („we found Cluj-Napoca, Cluj county") before saving.

Response structure

FieldTypeDescription
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 The county extracted from the text, or null if none was recognised.
data.parsat.localitate string The locality extracted.
data.parsat.strada string The street extracted, without its type (Str., Bd.).
data.parsat.numar string The house number extracted.
data.parsat.cod_postal null The postal code extracted.
data.parsat.detalii null The rest: block, staircase, floor, flat.
data.componente.*.stare Per field: whether it was found, confirmed in the nomenclature, or merely assumed.
data.rezultate[].numar object The house number matched, with its postal code and coordinates.
data.rezultate[].strada object The street matched, with postal code and coordinates.
meta.actualizat object When the administrative nomenclature and the street nomenclature were last updated.

Response examples

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

Error codes

CodeSlugWhen it occurs
401neautentificatToken missing, invalid, expired or revoked.
403feature_indisponibilThe current plan does not include the feature the route depends on.
422validareAn undeclared parameter or a value that fails validation (q). The offending field is in detalii.
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": "validare",
        "mesaj": "An undeclared parameter or a value that fails validation (q). The offending field is in detalii.",
        "detalii": {
            "q": [
                "The value sent does not satisfy the parameter rule."
            ]
        }
    }
}