Vragen · Adressen

Hoe voeg ik adres-autocomplete toe aan mijn formulier?

Wat degene die invult ziet

Iemand typt “kalverstr” en ziet “Kalverstraat”, met de plaatsen waar die straat bestaat; is de plaats al ingevuld, dan beperken de suggesties zich daartoe. Na de keuze van de straat typt hij het huisnummer en het formulier zegt of het bestaat: in Nederland bepaalt het huisnummer de postcode, en de postcode die binnenkomt is de juiste voor dat nummer en dat straatdeel, niet een algemene code van de plaats.

Bij de selectie worden de velden straat, huisnummer, postcode en plaats gevuld met het record dat door de engine is gegaan, hetzelfde als bij de adresverificatie. Het bestand wordt schoon geboren in plaats van achteraf te worden opgeschoond.

Hoe je ervoor betaalt

Per sessie, niet per toetsaanslag. De suggesties tijdens het typen zijn gratis; er wordt één bewerking geteld op het moment dat de gebruiker het adres selecteert en de velden worden gevuld. Verandert hij daarna het huisnummer en selecteert hij opnieuw in dezelfde sessie, dan betaal je niet nog een keer. Elke sessie laat tot dertig aanvragen toe en geldt tien minuten. De prijslijst staat op de prijzenpagina.

Hoe je het integreert

Drie onderdelen:

1. Een API-token, uit je account.
2. Een kleine proxy op je server: een pagina die de aanvraag van de browser ontvangt, het token toevoegt en doorstuurt naar ons endpoint. Die is nodig omdat het token nooit in code mag staan die in de browser draait.
3. De widget ra-suggerisci.js, zonder afhankelijkheden: je geeft hem het adres van de proxy en de selectors van de formuliervelden, en hij doet de rest: hij wacht zelf terwijl er getypt wordt, gebruikt de al ingevulde velden als context en vult de velden bij de keuze.

Wie het liever zelf doet, roept rechtstreeks het endpoint /api/v1/suggest aan: een sessie-identificatie die de client aanmaakt, de getypte tekst, de al bekende velden als context; daarna de selectie-actie met de gekozen straat en het huisnummer. Alles staat in de API-documentatie, en op de pagina autocomplete in je formulier vind je de drie bestanden klaar om over te nemen.

Bijzondere gevallen

• Andere landen: de suggesties bestaan in elk land met een adressenregister in dienst (de lijst); het formulier geeft het door de gebruiker gekozen land door en de widget zoekt daar, met de vorm van huisnummer en postcode van dat land. De gebruiker mag alles in één veld schrijven (“Kalverstraat 92 Amsterdam”, of in Nederland zelfs “1012PH 92”): het antwoord zegt hoe het gelezen is (parsed: straat, huisnummer, postcode). In een land zonder register zegt het antwoord dat en opent het geen sessie: het invullen gaat met de hand verder, zonder afboeking.
• WooCommerce, PrestaShop en Joomla: je hoeft niets te schrijven, er zijn de WooCommerce-plugin, de PrestaShop-module en de plugin voor Joomla-formulieren, met autocomplete bij de checkout of in het formulier en verificatie van wat wordt verzonden.
• Straat die niet verschijnt: de gebruiker kan het adres altijd volledig uitschrijven; het record gaat later door de verificatie, uit het bestand of via de API.
• Meerdere formulieren, meerdere sites: hetzelfde token bedient alle formulieren; de proxy kan op elke site staan of er kan één zijn.

Wat er met de velden gebeurt

De straat wordt aangevuld in de juiste vorm, de plaats gekozen uit de plaatsen die die straat hebben, de postcode door de engine ingevuld. Met het huisnummer komt de postcode van dat straatdeel, geverifieerd in het nationale register.