Spørgsmål · Adresser

Findes der et API til at normalisere adresser?

Hvad kaldet gør

Endpointet for kontaktverificering sætter adressen i landets postform, og med den det navn, der følger med. Det læser vej, husnummer, postnummer og by sammen, ikke ét felt ad gangen, 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.

Sådan kommer resultatet tilbage

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. Intet rettes nogensinde i stilhed: ændrer vi noget, fortæller vi det, og er vi ikke sikre, siger vi det lige så tydeligt i stedet for at gætte. 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.

Autofuldførelse 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 ved valget i stedet for at skulle tjekkes bagefter med et separat kald. Bruges fra din egen server, som fungerer som proxy til endpointet: tokenet må aldrig komme ud i slutbrugerens browser.

Hvornår det giver mening at integrere

Det giver mening, når adressen kommer ind i registret igen og igen, ikke én gang: 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.

Fejl, grænser og den fulde dokumentation

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. En adresse, der ikke kan normaliseres, er ikke en API-fejl: svaret kommer under alle omstændigheder, 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.