Vragen · Adressen

Is er een API om adressen te normaliseren?

Wat de aanroep doet

Het endpoint voor contactverificatie zet het adres in de postvorm van zijn land, en de naam die erbij hoort. Het leest straat, huisnummer, postcode en plaats samen, niet één veld tegelijk, en verklaart elke correctie. Het land gaat in country_code (ISO 3166-1) of in country, geschreven zoals het komt.

Eén contact per keer in de body van het verzoek, of een lijst in het veld items, tot vijfhonderd per aanroep. Elke aanroep heeft een token nodig, dat je na registratie in je account aanmaakt en meegeeft in de header Authorization: Bearer. Het token kan een vervaldatum krijgen, of geldig blijven tot je het intrekt.

Hoe het resultaat terugkomt

Het antwoord heeft twee vormen van hetzelfde adres: een leesbare met accenten, en de postvorm voor het printen van etiketten, in hoofdletters. Je hebt beide nodig om verschillende redenen: de eerste om het adres aan een medewerker of in een interface te tonen, de tweede voor het eigenlijke printen.

Daarbij komt een uitkomst in trefwoorden — correct, gewijzigd met het detail van wat er veld voor veld is veranderd, of te controleren wanneer het adres niet met zekerheid te reconstrueren is, met de reden in klare taal: straat niet gevonden in de gemeente, onvoldoende gegevens, huisnummer niet gevonden. Niets wordt ooit stilzwijgend gecorrigeerd: als we iets veranderen zeggen we het, en als we niet zeker zijn zeggen we dat even duidelijk in plaats van te gokken. Waar het register in dienst is krijg je ook de coördinaten van het huisnummer, de gemeentecode en, in steden die er een hebben, de wijk.

Eén adres of bulkopdrachten

Onder de vijfhonderd verzoeken krijg je het antwoord meteen, in dezelfde aanroep: het typische geval van een registratieformulier of een checkout, waar het adres geverifieerd moet worden op het moment dat de gebruiker het typt. Voor grotere lijsten, tot honderdduizend adressen tegelijk, voeg je "async": true toe: het verzoek geeft meteen een opdrachtcode terug en de verwerking komt in de wachtrij, dezelfde die de bulkopdrachten van de site afhandelt. Je leest het resultaat terug met een GET op hetzelfde endpoint met de code, in JSON of, als je een bestand wilt downloaden, in CSV.

Autocomplete voor je formulieren

Als je een adresformulier bouwt, geeft /api/v1/suggest autocomplete terwijl de gebruiker typt: straat, plaats en huisnummer worden gaandeweg voorgesteld, met het veld al geverifieerd bij de selectie in plaats van het later met een aparte aanroep te moeten controleren. Te gebruiken vanaf een eigen server, die als proxy naar het endpoint dient: het token mag nooit in de browser van de eindgebruiker verschijnen.

Wanneer integreren zinvol is

Het is zinvol wanneer het adres keer op keer in je bestand binnenkomt, niet eenmalig: een registratieformulier, een e-commerce-checkout, een CRM dat uit meerdere kanalen wordt gevuld. Het daar verifiëren, op het moment dat het binnenkomt, voorkomt dat foute adressen zich opstapelen die dan vóór elke mailing in bulk moeten worden opgeschoond. Heb je daarentegen al een lijst die één keer moet worden rechtgezet, dan is het eenvoudiger die als Excel- of CSV-bestand via de site te uploaden: dezelfde engine, zonder een regel code te schrijven.

Fouten, limieten en volledige documentatie

Elk antwoord heeft een HTTP-code die past bij wat er is gebeurd: 401 als het token ontbreekt of ongeldig is, 413 als de batch de limiet overschrijdt, 429 als je het toegestane aantal verzoeken per minuut hebt overschreden, 402 als het krediet niet volstaat voor de aanroep. Een adres dat niet te normaliseren is, is geen API-fout: het antwoord komt toch, met de uitkomst die uitlegt waarom.

Op de API-pagina vind je alle endpoints — adres, ontdubbelen, e-mail, telefoon, website, naamverrijking — met de parameters, de curl-voorbeelden en de foutcodes voluit. Werk je met een tool die specificaties importeert, dan is er ook openapi.json.

Een minimale aanroep

Het volledige antwoord bevat ook de postvorm, het detail van elk gewijzigd veld, de coördinaten van het huisnummer en de gegevens zoals je ze hebt gestuurd, ter vergelijking.