Webform Address Autocomplete Flanders

Webform Address Autocomplete Flanders lets visitors fill in a Belgian (Flemish) address in a webform by typing it into a single search field. Suggestions come from the official Flemish Address Register (Adressenregister), and the chosen address is split into street, postal code and city automatically.

Visitors don't have to fill in separate street, number, postal code and city fields, and site owners get addresses that match the official register. If an address can't be found, visitors can still enter it by hand.

Features

• Address search on webform address elements. Adds a search field to the Address element that suggests matching addresses from the Flemish Address Register (basisregisters.vlaanderen.be) while the visitor types. Only addresses that
  are in use are suggested.
• Structured results. Choosing a suggestion fills the address element's street (including house and box number), postal code and city, so submissions store a normal structured address.
• Limit to one municipality. Optionally restrict suggestions per element to a single municipality using its NIS code, for example a municipal form that only accepts local addresses.
• "My address isn't listed" fallback. A checkbox lets visitors switch to manual entry of street, postal code and city, for new builds or addresses missing from the register.
• Validation. Typed text that doesn't match a chosen address is rejected both in the browser and on the server, so a required address can't be submitted as free text by mistake. An exact typed match is accepted without clicking a suggestion.
• Custom "no results" message. Set the text shown when no address matches, per element.
• Belgium only. The country is fixed to Belgium, so no country selector is shown.

Typical use cases: municipal and government forms, service requests, registrations and any other webform aimed at people with an address in Flanders (or Brussels and Wallonia, as far as the register covers them).

Post-Installation

1. Enable the module. Every webform Address element on the site now shows the address search and is limited to Belgium. No other setup is needed.
2. To configure an element, edit it in the webform builder (Structure » Webforms » Build). In the Address settings fieldset you'll find:
   • Limit to NIS code: a single municipality NIS code (e.g. 12040). Leave it empty to search all municipalities.
   • Autocomplete no results message: the text shown when nothing matches.
3. Marking the address element as required makes the search field required. When the visitor switches to manual entry, street, postal code and city become required instead.

The API base URL defaults to https://api.basisregisters.vlaanderen.be/v2. There is no settings form; to point to another endpoint, for example a proxy, override webform_address_autocomplete_flanders.settings:api_url in configuration or settings.php.

Address lookups go through your own site, so visitors' browsers never call the register directly. The register's public API requires no API key.

Additional Requirements

• Drupal 10 or 11
• Webform
• Address
• Outbound HTTPS access from your web server to api.basisregisters.vlaanderen.be

Recommended modules/libraries

None required. Webform UI (part of Webform) is needed to configure the per-element settings in the browser.

Similar projects

• Webform Address Autocomplete provides its own webform element with pluggable providers (Google Maps, Mapbox, France, Switzerland). Providers must return complete addresses in a single call and are configured site-wide. It has no per-element filtering, manual-entry fallback or check that a suggestion was actually chosen.
• Address Autocomplete adds autocomplete to Address fields and webforms with similar global providers.

This module is built specifically for the Flemish Address Register. It uses the register's two-step search-then-detail API and works on the existing Address webform element. It adds the per-element municipality filter, a manual fallback and server-side validation that the other projects don't offer.

Supporting this Module

Development is sponsored by Leapforward. Bug reports, patches and merge requests are welcome in the issue queue.

Community Documentation

• Flemish Address Register API documentation