Spørsmål · Adresser

Finnes det et API for å normalisere adresser?

Hva kallet gjør

Endepunktet for kontaktkontroll setter adressen i landets postform, og navnet som hører til. Det leser gate, husnummer, postnummer og sted sammen, ikke ett felt om gangen, og oppgir hver rettelse. Landet angis i country_code (ISO 3166-1) eller i country, skrevet som det faller seg.

Én kontakt om gangen i forespørselens body, eller en liste i feltet items, opptil fem hundre per kall. Hvert kall trenger et token, som du lager i kontoen din etter registrering, og sender i headeren Authorization: Bearer. Tokenet kan gis en utløpsdato, eller forbli gyldig til du tilbakekaller det.

Hvordan resultatet kommer tilbake

Svaret har to former av samme adresse: en lesbar med diakritiske tegn, og postformen for etikettutskrift, med store bokstaver. Du trenger begge av ulike grunner: den første for å vise adressen til en saksbehandler eller i et grensesnitt, den andre for selve utskriften.

Med dem kommer et resultat i nøkkelord — korrekt, endret med detaljen om hva som er endret felt for felt, eller til kontroll når adressen ikke kan rekonstrueres med sikkerhet, med årsaken i klartekst: gate ikke funnet i kommunen, utilstrekkelige data, husnummer ikke funnet. Ingenting rettes noen gang i stillhet: endrer vi noe, sier vi det, og er vi usikre, sier vi det like tydelig i stedet for å gjette. Der registeret er i drift får du også husnummerets koordinater, kommunekoden og, i byer som har det, bydelen.

Enkeltadresse eller jobber i bulk

Under fem hundre forespørsler får du svaret med en gang, i samme kall: det typiske tilfellet for et registreringsskjema eller en kasse, der adressen skal kontrolleres idet brukeren skriver den. For større lister, opptil hundre tusen adresser om gangen, legger du til "async": true: forespørselen returnerer straks en jobbkode og behandlingen går inn i køen, den samme som håndterer jobber i bulk lastet opp fra nettstedet. Du leser resultatet tilbake med en GET mot samme endepunkt med koden, som JSON eller, hvis du trenger en fil å laste ned, som CSV.

Autofullføring for skjemaene dine

Bygger du et adresseskjema, gir /api/v1/suggest deg autofullføring mens brukeren skriver: gate, sted og husnummer foreslås etter hvert, med feltet allerede kontrollert ved valget i stedet for å måtte sjekke det etterpå med et eget kall. Skal brukes fra en egen server som fungerer som proxy mot endepunktet: tokenet må aldri vises i sluttbrukerens nettleser.

Når det gir mening å integrere

Det gir mening når adressen kommer inn i registeret gang på gang, ikke én gang: et registreringsskjema, en nettbutikk-kasse, et CRM som mates fra flere kanaler. Å kontrollere den der, idet den kommer inn, unngår at feil adresser hoper seg opp og må ryddes i bulk før hver utsendelse. Har du derimot allerede en liste som skal rettes én gang, er det enklere å laste den opp som Excel- eller CSV-fil fra nettstedet: samme motor, uten å skrive en linje kode.

Feil, grenser og fullstendig dokumentasjon

Hvert svar har en HTTP-kode som stemmer med det som skjedde: 401 hvis tokenet mangler eller er ugyldig, 413 hvis bulken overskrider grensen, 429 hvis du har overskredet tillatt antall forespørsler per minutt, 402 hvis kreditten ikke dekker kallet. En adresse som ikke kan normaliseres, er ikke en API-feil: svaret kommer likevel, med resultatet som forklarer hvorfor.

På API-siden finner du alle endepunktene — adresse, deduplisering, e-post, telefon, nettsted, navneberikelse — med parametere, curl-eksempler og feilkoder i sin helhet. Arbeider du med et verktøy som importerer spesifikasjoner, finnes også openapi.json.

Et minimalt kall

Det fullstendige svaret inneholder også postformen, detaljen for hvert endrede felt, husnummerets koordinater og dataene slik du sendte dem, til sammenligning.