Frågor · API

Finns det ett API för att validera och normalisera adresser?

Vad API:et för adressvalidering gör

Endpointen för kontaktkontroll sätter adressen i sitt lands postform, och namnet som hör till. I samma bearbetning kontrollerar den också e-post, telefon och webbplats, om du skickar dem. Den läser gata, husnummer, postnummer och ort tillsammans 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.

Valideringens resultat, fält för fält

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. Varje rättelse redovisas, och när motorn är osäker säger den det lika tydligt. 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 av adresser 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 när förslaget väljs, utan 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 löpande: 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.

Felkoder, gränser och fullständig API-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. Även när en adress inte kan normaliseras kommer svaret, 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.