oneapi
Sign in
Locations v1 / Validare adrese

Validate the format (text)

Takes a free string (q) and says whether it looks like an address: tip (adresa / entitate / cod_postal / necunoscut), pare_adresa, semnale (format + gazetteer) and a motiv. It uses the gazetteer to know whether a „place" actually exists — „asdf" → necunoscut, „Cluj-Napoca" → entitate. It does NOT resolve the entity (that is what /validare/parsare does).

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

Query parameters

NameTypeDescriptionAccepted values
qoptional string | null The string to classify (e.g. „Str. Memorandumului 28, Cluj-Napoca"). max 255 car.

How it behaves

  • Takes a free string (q) and says whether it looks like an address, combining FORMAT (thoroughfare type / number / code) with a GAZETTEER signal (does the place actually exist in our database?).
  • tip: adresa (street/number level) | entitate (a known place name) | cod_postal | necunoscut. pare_adresa is true only for adresa.
  • The gazetteer sharpens the verdict: „asdf qwerty" → necunoscut (no real place); „Cluj-Napoca"/„Baia Mare" → entitate (recognised). It does NOT resolve WHICH entity (no ids) — that is what /validare/parsare and /validare/adresa do.

What it is for

  • Pre-validation in a form: checking whether the user wrote a real address (tip=adresa) or just a city or garbage — before the expensive resolution flow.
  • UX guidance: at tip=entitate you suggest „add the street and number"; at tip=necunoscut you reject the input (e.g. „asdf 123").
  • A cheap front filter (no database): weed out the garbage before hitting the resolution routes.

Response structure

All fields below live inside data.

FieldTypeDescription
parsat object Componentele extrase: judet, localitate, strada, numar, cod_postal, detalii.
tip string adresa | entitate | cod_postal | necunoscut.
detaliu_tip string La adresa: completa | partiala. La entitate: localitate | judet | localitate_cu_judet.
pare_adresa boolean true doar când tip=adresa.
semnale object Booleeni: format (tip_strada, numar, cod_postal, localitate, judet) + gazetteer (localitate_cunoscuta, judet_cunoscut, strada_cunoscuta).
motiv string Explicație scurtă a clasificării.
parsat.judet null The county extracted from the text, or null if none was recognised.
parsat.localitate string The locality extracted.
parsat.strada string The street extracted, without its type (Str., Bd.).
parsat.numar null The house number extracted.
parsat.cod_postal null The postal code extracted.
parsat.detalii null The rest: block, staircase, floor, flat.
semnale.tip_strada boolean A thoroughfare marker was found („Str.", „Bd.").
semnale.numar boolean Something that looks like a house number was found.
semnale.cod_postal boolean A six-digit postal code was found.
semnale.localitate boolean A locality candidate was found.
semnale.judet boolean A county candidate was found.
semnale.localitate_cunoscuta boolean This is where „no database" ends: this signal confirms the name really does exist in the nomenclature.
semnale.judet_cunoscut boolean The county found exists in the nomenclature.
semnale.strada_cunoscuta boolean The street found exists in the nomenclature.

Response examples

GEThttps://oneapi.ro/api/locations/v1/validare/text?q=Strada%20Memorandumului%2028,%20Cluj-Napoca
{
    "data": {
        "parsat": {
            "judet": null,
            "localitate": "Cluj-Napoca",
            "strada": "Memorandumului 28",
            "numar": null,
            "cod_postal": null,
            "detalii": null,
            "judet_din_marker": false
        },
        "tip": "adresa",
        "detaliu_tip": "completa",
        "pare_adresa": true,
        "semnale": {
            "tip_strada": true,
            "numar": false,
            "cod_postal": false,
            "localitate": true,
            "judet": false,
            "localitate_cunoscuta": true,
            "judet_cunoscut": false,
            "strada_cunoscuta": true
        },
        "motiv": "tip de stradă + număr + localitate cunoscută"
    }
}

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