Spørgsmål · API

Findes der et API til adressevalidering og normalisering af adresser?

Hvad API'et til adressevalidering gør

Endpointet for adressevalidering sætter adressen i landets postform, og med den det navn, der følger med. I samme behandling kontrollerer det også e-mail, telefon og website, hvis du sender dem. Det læser vej, husnummer, postnummer og by sammen og oplyser hver rettelse. Landet angives i feltet country_code (ISO 3166-1) eller i feltet country, skrevet på enhver måde.

Én kontakt ad gangen i forespørgslens body eller en liste i feltet items, op til fem hundrede pr. kald. Hvert kald kræver et token, som du opretter på din konto efter registreringen og sender med i headeren Authorization: Bearer. Tokenet kan få en udløbsdato eller gælde, indtil du tilbagekalder det.

Resultatet af valideringen, felt for felt

Svaret indeholder to former af samme adresse: en læsbar med æ, ø og å, og postformen til udskrivning af etiketter, med store bogstaver. Du har brug for begge, af forskellige grunde: den første til at vise adressen for en medarbejder eller i en brugerflade, den anden til selve udskrivningen.

Med dem følger et resultat i nøgleord — korrekt, ændret med detaljerne om, hvad der blev ændret felt for felt, eller skal tjekkes, når adressen ikke kan genopbygges med sikkerhed, med årsagen i klar tekst: vej ikke fundet i kommunen, utilstrækkelige data, husnummer ikke fundet. Hver rettelse oplyses, og når motoren ikke er sikker, siger den det lige så tydeligt. Hvor registret er i drift, får du også husnummerets koordinater, kommunekoden og, i de byer, der har dem, bydelen.

Én adresse eller batchkørsler

Under fem hundrede får du svaret med det samme, i samme kald: det typiske tilfælde er en tilmeldingsformular eller en checkout, hvor adressen skal tjekkes i det øjeblik, brugeren skriver den. Til større lister, op til hundrede tusind adresser ad gangen, tilføjer du "async": true: forespørgslen returnerer straks en jobkode, og behandlingen går i kø, den samme, som håndterer batchjob uploadet fra websitet. Du læser resultatet med et GET-kald til samme endpoint med koden, i JSON eller, hvis du har brug for en fil at downloade, i CSV.

Autocomplete af adresser i dine formularer

Bygger du en adresseformular, giver /api/v1/suggest autofuldførelse, mens brugeren skriver: vej, by og husnummer foreslås undervejs, og feltet er allerede verificeret, når forslaget vælges, uden et separat kald. Bruges fra din egen server, som fungerer som proxy til endpointet: tokenet må aldrig komme ud i slutbrugerens browser.

Hvornår integrationen kan betale sig

Det giver mening, når adressen kommer ind i registret løbende: en tilmeldingsformular, en webshops checkout, et CRM, der fyldes fra flere kanaler. At tjekke den dér, i det øjeblik den kommer ind, forhindrer, at forkerte adresser hober sig op og skal ryddes op i partier før hver forsendelse. Har du derimod allerede en liste, der skal rettes én gang, er det enklere at uploade den som Excel- eller CSV-fil fra websitet: samme motor, uden en eneste linje kode.

Fejlkoder, grænser og dokumentationen til API'et

Hvert svar har en HTTP-kode, der svarer til det, der skete: 401, hvis tokenet mangler eller er ugyldigt, 413, hvis partiet overskrider grænsen, 429, hvis du har overskredet det tilladte antal forespørgsler i minuttet, 402, hvis kreditten ikke rækker til kaldet. Også når en adresse ikke kan normaliseres, kommer svaret, med det resultat, der forklarer hvorfor.

På API-siden finder du alle endpoints — adresse, deduplikering, e-mail, telefon, website, berigelse af navn — med parametre, curl-eksempler og fejlkoder i deres helhed. Arbejder du med et værktøj, der importerer specifikationer, findes der også openapi.json.

Et minimalt kald

Det fulde svar indeholder også postformen, detaljerne for hvert ændret felt, husnummerets koordinater og dataene, som du sendte dem, til sammenligning.