Problema: adresele românești nu sunt uniforme
Dacă ai construit vreodată un formular de livrare sau un flux de onboarding cu adrese românești, știi că datele arată altfel de la un user la altul:
- „Str. Mihai Vitezu 12" vs „Strada Mihai Viteazu nr. 12" vs „Mihai Viteazu 12, Cluj" - „ş" cu sedilă vs „ș" cu virgulă — aceeași literă, coduri Unicode diferite - „Cluj" vs „Cluj-Napoca" — ambele corecte, nici una canonică
Rezultatul: duplicate în baza de date, livrări eșuate și erori greu de depanat la reconciliere.
Cum funcționează verificarea posty.ro
Endpoint-ul POST /v1/addresses/verify acceptă o adresă fie ca șir freeform, fie ca câmpuri structurate:
{
"freeform": "Str. Mihai Vitezu 12, cluj"
}Răspunsul conține un verdict (verified, corrected, partial, unverifiable), corecții pe fiecare câmp și un scor de încredere:
{
"verdict": "corrected",
"confidence": 0.92,
"input": { "street": "Str. Mihai Vitezu", "house_number": "12", "locality": "cluj" },
"normalized": {
"postal_code": "400151",
"locality": "Cluj-Napoca",
"county": "Cluj",
"county_code": "CJ",
"street": "Strada Mihai Viteazu",
"house_number": "12"
},
"corrections": [
{ "field": "street", "from": "Mihai Vitezu", "to": "Mihai Viteazu", "reason": "diacritic" },
{ "field": "locality", "from": "cluj", "to": "Cluj-Napoca", "reason": "casing" }
],
"metadata": { "source_versions": { "baseline": "2024-Q1" } }
}Integrare în practică
Cel mai frecvent pattern este validarea la momentul completării formularului, nu post-procesarea:
1. La submit: trimite adresa la /verify înainte de a salva în baza de date. 2. Dacă verdict === "corrected": arată userului forma canonică și cere confirmare. 3. Dacă verdict === "unverifiable": blochează comanda și cere o adresă corectată. 4. Stochează forma canonică, nu ce a scris userul — reconcilierea devine trivială.
Ce determină scorul de încredere
Scorul reflectă câte câmpuri au necesitat corecții și cât de mari au fost diferențele. O adresă cu diacritice incorecte dar stradă și număr recunoscute produce un scor peste 0.85. O adresă cu stradă nerecunoscută sau județ lipsă coboară sub 0.60.
Poți seta propriul prag de acceptanță: unii clienți trec orice peste 0.70, alții cer 0.90 pentru livrare fără confirmare umană.
Sursele de date
Verificarea se bazează pe trei surse reconciliate: - Poșta Română — baza de coduri poștale, ediția mai 2016 - SIRUTA (INS) — nomenclatorul unităților Teritorial-Administrative - OpenStreetMap — acoperire la nivel de stradă, actualizată periodic
Fiecare răspuns include versiunea bazei de date în metadata.source_versions, util la audit.