Locations v1 / Validare adrese

Validează formatul (text)

Ia un string liber (q) și spune dacă seamănă cu o adresă: tip (adresa / entitate /
cod_postal / necunoscut), pare_adresa, semnale (format + gazetteer) și un motiv.
Folosește gazetteer-ul ca să știe dacă un „loc" chiar există — „asdf" → necunoscut,
„Cluj-Napoca" → entitate. NU rezolvă entitatea (asta face /validare/parsare).

GET

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

Parametri de interogare

NumeTipDescriereValori acceptate

qopțional string | null Stringul de clasificat (ex. „Str. Memorandumului 28, Cluj-Napoca"). max 255 car.

Cum se comportă

Ia un string liber (q) și spune dacă seamănă cu o adresă, combinând FORMAT-ul (tip stradă / număr / cod) cu un semnal de GAZETTEER (locul chiar există în baza noastră?).
tip: adresa (nivel de stradă/număr) | entitate (nume de loc cunoscut) | cod_postal | necunoscut. pare_adresa e true doar la adresa.
Gazetteer-ul ascute verdictul: „asdf qwerty" → necunoscut (niciun loc real); „Cluj-Napoca"/„Baia Mare" → entitate (recunoscute). NU rezolvă CARE entitate (id-uri) — asta o fac /validare/parsare și /validare/adresa.

La ce folosește

Pre-validare într-un formular: verifici dacă userul a scris o adresă reală (tip=adresa) sau doar un oraș/gunoi — înainte de fluxul scump de rezoluție.
Ghidare UX: la tip=entitate îi sugerezi „adaugă strada și numărul"; la tip=necunoscut respingi input-ul (ex. „asdf 123").
Filtru în față (ieftin, fără bază de date): trie gunoiul înainte să lovești rutele de rezoluție.

Structura răspunsului

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

CâmpTipDescriere

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 Județul extras din text, sau null dacă n-a fost recunoscut.

parsat.localitate string Localitatea extrasă.

parsat.strada string Strada extrasă, fără tipul ei (Str., Bd.).

parsat.numar null Numărul poștal extras.

parsat.cod_postal null Codul poștal extras.

parsat.detalii null Restul: bloc, scară, etaj, apartament.

semnale.tip_strada boolean S-a găsit un indicator de arteră („Str.", „Bd.").

semnale.numar boolean S-a găsit ceva ce arată a număr poștal.

semnale.cod_postal boolean S-a găsit un cod poștal de 6 cifre.

semnale.localitate boolean S-a găsit un candidat de localitate.

semnale.judet boolean S-a găsit un candidat de județ.

semnale.localitate_cunoscuta boolean Aici se termină „fără bază de date": semnalul ăsta confirmă că numele chiar există în nomenclator.

semnale.judet_cunoscut boolean Județul găsit există în nomenclator.

semnale.strada_cunoscuta boolean Strada găsită există în nomenclator.

Exemple de răspuns

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

entitate (localitate cunoscută), nu adresă.

GEThttps://oneapi.ro/api/locations/v1/validare/text?q=Cluj-Napoca

{
    "data": {
        "parsat": {
            "judet": null,
            "localitate": "Cluj-Napoca",
            "strada": null,
            "numar": null,
            "cod_postal": null,
            "detalii": null,
            "judet_din_marker": false
        },
        "tip": "entitate",
        "detaliu_tip": "localitate",
        "pare_adresa": false,
        "semnale": {
            "tip_strada": false,
            "numar": false,
            "cod_postal": false,
            "localitate": true,
            "judet": false,
            "localitate_cunoscuta": true,
            "judet_cunoscut": false,
            "strada_cunoscuta": true
        },
        "motiv": "localitate cunoscută"
    }
}

GEThttps://oneapi.ro/api/locations/v1/validare/text?q=400001

{
    "data": {
        "parsat": {
            "judet": null,
            "localitate": null,
            "strada": null,
            "numar": null,
            "cod_postal": "400001",
            "detalii": null,
            "judet_din_marker": false
        },
        "tip": "cod_postal",
        "detaliu_tip": null,
        "pare_adresa": false,
        "semnale": {
            "tip_strada": false,
            "numar": false,
            "cod_postal": true,
            "localitate": false,
            "judet": false,
            "localitate_cunoscuta": false,
            "judet_cunoscut": false,
            "strada_cunoscuta": false
        },
        "motiv": "doar un cod poștal de 6 cifre"
    }
}

necunoscut — niciun loc real recunoscut.

GEThttps://oneapi.ro/api/locations/v1/validare/text?q=asdf%20qwerty

{
    "data": {
        "parsat": {
            "judet": null,
            "localitate": "asdf qwerty",
            "strada": null,
            "numar": null,
            "cod_postal": null,
            "detalii": null,
            "judet_din_marker": false
        },
        "tip": "necunoscut",
        "detaliu_tip": null,
        "pare_adresa": false,
        "semnale": {
            "tip_strada": false,
            "numar": false,
            "cod_postal": false,
            "localitate": true,
            "judet": false,
            "localitate_cunoscuta": false,
            "judet_cunoscut": false,
            "strada_cunoscuta": false
        },
        "motiv": "nume de loc necunoscut în baza noastră"
    }
}

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	validare	Un parametru nedeclarat ori o valoare care nu trece validarea (`q`). Câmpul vinovat e în `detalii`.
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": "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."
            ]
        }
    }
}