oneapi
Sign in
Locations v1 / Validare adrese

Reconcile text ↔ structured

Takes TWO representations of the same address — a free string q AND/OR structured fields — overlays them field by field and REPORTS: where they complete each other, where they agree and where they conflict. It does not arbitrate (conflicting fields do not enter reconciliat). The county is compared canonically (code „CJ" ≡ name „Cluj").

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

Query parameters

NameTypeDescriptionAccepted values
qoptional string | null The address as free text (e.g. „Str. Memorandumului 28, Cluj-Napoca"). max 255 car.
judetoptional string | null The county from the form (code „CJ" or name „Cluj"). max 100 car.
localitateoptional string | null The locality from the form. max 150 car.
stradaoptional string | null The street from the form. max 200 car.
numaroptional string | null The house number from the form. max 30 car.
cod_postaloptional string | null The postal code from the form. max 10 car.

How it behaves

  • Takes TWO representations of the same address — a free string q AND/OR structured fields (judet/localitate/strada/numar/cod_postal) — and overlays them field by field.
  • It REPORTS, it does not arbitrate: concordanta[camp].stare ∈ {doar_q, doar_structural, concorda, conflict}. Conflicting fields do NOT enter reconciliat — they appear only in conflicte; the client decides who wins.
  • The county is compared canonically: „CJ" (code) and „Cluj" (name) match, and do not raise a false conflict. A number left at the tail of the street in q („Memorandumului 28") is moved automatically into numar.

What it is for

  • Ecommerce with dropdowns AND a free-text field: comparing what the user picked (county/locality from the dropdown) with what they typed, and flagging when the two disagree.
  • Catching mistakes at checkout: the user picked „Cluj" from the dropdown but typed an address in Bucharest → you catch the conflict before a wrong delivery.
  • Cross-completion: the dropdown gives county and locality, the text gives street and number → you combine them automatically into a full address (fields without conflict enter reconciliat).

Response structure

FieldTypeDescription
data.reconciliat object Adresa pe care cele două surse o susțin (fără câmpurile în conflict).
data.concordanta object Per câmp: {stare, valoare} sau {stare:conflict, structural, din_q}.
data.conflicte[] object The fields where the free text and the structured input say different things.
data.are_conflicte boolean true dacă există cel puțin un conflict.
data.reconciliat.judet string The county resulting from overlaying the free text on the structured fields.
data.reconciliat.localitate string The resulting locality.
data.reconciliat.strada string The resulting street.
data.concordanta.*.stare Per field: concordanta, conflict, or present in one source only. This route is a REPORT, not an arbiter — it does not decide which source is right.
data.concordanta.*.valoare The value kept for that field.
meta.actualizat object When the administrative nomenclature was last updated.

Response examples

Structuratul dă județ+localitate, q dă strada+numărul.

GEThttps://oneapi.ro/api/locations/v1/validare/reconciliere?judet=CJ&localitate=Cluj-Napoca&q=Strada%20Memorandumului%2028
{
    "data": {
        "reconciliat": {
            "judet": "CJ",
            "localitate": "Cluj-Napoca",
            "strada": "Memorandumului",
            "numar": "28"
        },
        "concordanta": {
            "judet": {
                "stare": "doar_structural",
                "valoare": "CJ"
            },
            "localitate": {
                "stare": "doar_structural",
                "valoare": "Cluj-Napoca"
            },
            "strada": {
                "stare": "doar_q",
                "valoare": "Memorandumului"
            },
            "numar": {
                "stare": "doar_q",
                "valoare": "28"
            }
        },
        "conflicte": [],
        "are_conflicte": false
    },
    "meta": {
        "actualizat": {
            "administrativ": "2026-08-15T16: 39: 14+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, judet, localitate, strada, numar, cod_postal). 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, judet, localitate, strada, numar, cod_postal). The offending field is in detalii.",
        "detalii": {
            "q": [
                "The value sent does not satisfy the parameter rule."
            ]
        }
    }
}