Frågor · Adresser

Finns det ett API för att normalisera adresser?

Vad anropet gör

Endpointen för kontaktkontroll sätter adressen i sitt lands postform, och namnet som hör till. Den läser gata, husnummer, postnummer och ort tillsammans, inte ett fält i taget, och redovisar varje rättelse. Landet anges i country_code (ISO 3166-1) eller i country, skrivet hur som helst.

En kontakt i taget i förfrågans body, eller en lista i fältet items, upp till femhundra per anrop. Varje anrop kräver en token, som du skapar i ditt konto när du registrerat dig, och skickar i headern Authorization: Bearer. Token kan ges ett utgångsdatum, eller förbli giltig tills du återkallar den.

Hur resultatet kommer tillbaka

Svaret har två former av samma adress: en läsbar med diakritiska tecken, och postformen för etikettutskrift, med versaler. Du behöver båda av olika skäl: den första för att visa adressen för en handläggare eller i ett gränssnitt, den andra för själva utskriften.

Med dem kommer ett resultat i nyckelord — korrekt, ändrad med detaljen om vad som ändrats fält för fält, eller att kontrollera när adressen inte kan återskapas med säkerhet, med orsaken i klartext: gatan hittades inte i kommunen, otillräckliga uppgifter, husnumret hittades inte. Inget rättas någonsin i tysthet: ändrar vi något säger vi det, och är vi osäkra säger vi det lika tydligt i stället för att gissa. Där registret är i drift får du också husnumrets koordinater, kommunkoden och, i städer som har den, stadsdelen.

Enskild adress eller batchjobb

Under femhundra förfrågningar får du svaret direkt, i samma anrop: det typiska fallet för ett registreringsformulär eller en kassa, där adressen ska kontrolleras i samma stund som användaren skriver in den. För större listor, upp till hundratusen adresser på en gång, lägger du till "async": true: förfrågan returnerar genast en jobbkod och bearbetningen går in i kön, samma som hanterar batchjobb uppladdade från webbplatsen. Du läser tillbaka resultatet med en GET mot samma endpoint med koden, som JSON eller, om du behöver en fil att ladda ner, som CSV.

Autokomplettering för dina formulär

Om du bygger ett adressformulär ger /api/v1/suggest dig autokomplettering medan användaren skriver: gata, ort och husnummer föreslås efter hand, med fältet redan kontrollerat vid valet i stället för att behöva kontrollera det efteråt med ett separat anrop. Ska användas från en egen server som fungerar som proxy mot endpointen: token får aldrig visas i slutanvändarens webbläsare.

När det är vettigt att integrera

Det är vettigt när adressen kommer in i registret gång på gång, inte en enda gång: ett registreringsformulär, en e-handelskassa, ett CRM som matas från flera kanaler. Att kontrollera den där, i det ögonblick den kommer in, undviker att felaktiga adresser samlas på hög som sedan måste rensas i batch före varje utskick. Har du i stället redan en lista som ska rättas en gång är det enklare att ladda upp den som Excel- eller CSV-fil från webbplatsen: samma motor, utan att skriva en rad kod.

Fel, gränser och fullständig dokumentation

Varje svar har en HTTP-kod som stämmer med vad som hänt: 401 om token saknas eller är ogiltig, 413 om batchen överskrider gränsen, 429 om du överskridit tillåtet antal förfrågningar per minut, 402 om krediten inte räcker för anropet. En adress som inte kan normaliseras är inte ett API-fel: svaret kommer ändå, med resultatet som förklarar varför.

På API-sidan hittar du alla endpoints — adress, dubblettrensning, e-post, telefon, webbplats, namnberikning — med parametrar, curl-exempel och felkoder i sin helhet. Arbetar du med ett verktyg som importerar specifikationer finns även openapi.json.

Ett minimalt anrop

Det fullständiga svaret innehåller också postformen, detaljen för varje ändrat fält och uppgifterna som du skickade dem, för jämförelse; i länder med register i drift även husnumrets koordinater.