DataFirefly Address Lookup — Documentation

Overview

DataFirefly Address Lookup adds address autocomplete to PrestaShop 8 and 9 forms: the checkout, the “My address” page, the “My information” page and the registration form. The module relies on two engines: the French BAN API (api-adresse.data.gouv.fr), free and keyless, enabled by default for France, and Google Places as an option for international addresses.

The customer workflow is simple: they type their postcode, the city fills in automatically (or a municipality picker appears when several match); they start typing their street, suggestions appear; one click fills the street, postcode and city at once with a normalized address.

Requirements

• PrestaShop 8.0 to 9.x (Classic theme, Hummingbird or most third-party themes)
• PHP 7.4 or higher
• For Google Places only: a Google Cloud API key with the Places API and Maps JavaScript API enabled

Installation

1. In the PrestaShop back office, open Modules → Module Manager.
2. Click Upload a module and drop the dfaddresslookup.zip file.
3. PrestaShop installs the module and automatically registers the actionFrontControllerSetMedia and displayHeader hooks.
4. Click Configure to open the settings screen.

Right after installation, autocomplete is active for France with zero configuration: the BAN API is enabled by default and requires no key.

Configuration

French BAN API

Enable French BAN API — turns the French engine on or off. Enabled by default. The api-adresse.data.gouv.fr API is a free public service: no key, no subscription, an indicative limit of 50 requests per second per IP, far above checkout needs.

Auto-fill city from postal code — when the customer types a 5-digit French postcode, the city fills automatically if a single municipality matches; otherwise a municipality picker appears under the field. The module never overwrites a city already typed by the customer.

Google Places (optional)

Enable Google Places — turns the international engine on. Requires a valid API key; otherwise saving the configuration is rejected.

Google API key — your Google Cloud key. See the next section to create and secure it.

Allowed countries — comma-separated ISO 3166-1 alpha-2 codes (e.g. BE,CH,LU,DE). Google Places only triggers for those countries; empty field = all countries. This is the main lever to keep your Google Cloud billing under control.

Behavior

Minimum characters — number of characters before suggestions trigger (2 to 10, default 3).

Debounce (ms) — delay between the last keystroke and the API call (80 to 2000 ms, default 250). Increase it to reduce the number of requests, decrease it for snappier suggestions.

Highlight matched text — bolds the text typed by the customer inside each suggestion.

Getting a Google Places key

1. Open the Google Cloud Console and select or create a project.
2. In APIs & Services → Library, enable Places API and Maps JavaScript API.
3. In APIs & Services → Credentials, create an API key.
4. Restrict the key: Application restrictions → “HTTP referrers” → add your domain (e.g. *.yourshop.com/*); API restrictions → limit to Places API and Maps JavaScript API.
5. Paste the key into the module configuration and save.

How it works

Automatic engine switching

The module reads the country selected in the form’s id_country field. France → BAN engine. Another country present in the allowlist → Google Places. Country outside the list or no applicable engine → autocomplete silently disables and the form remains a classic input form. Switching is immediate on every country change, with no page reload.

One-page checkout compatibility and re-renders

The PrestaShop checkout re-renders the address form on every step change. The module watches the DOM with a MutationObserver and subscribes to the native events updatedAddressForm, updatedAddress, updatedDeliveryForm and changedCheckoutStep: autocomplete re-attaches automatically on each re-render. Each form is flagged after binding to prevent double attachment.

Multiple forms

If several address forms are displayed simultaneously (shipping + billing), each gets its own independent autocomplete, with its own dropdown and its own state.

Keyboard navigation and accessibility

The suggestion dropdown is fully keyboard-driven: up/down arrows to navigate, Enter to select, Escape to close. Suggestions carry the ARIA attributes role="listbox" and role="option".

Graceful degradation

If the API is unreachable (outage, offline customer, network blocking), no error is displayed: the form remains a classic manual input form. Autocomplete is a progressive enhancement, never a checkout blocker.

GDPR and privacy

• Autocomplete requests go directly from the customer browser to the BAN API (French public service) or Google Places.
• No data transits through your PrestaShop server during typing.
• No data ever transits through DataFirefly servers.
• The module sets no cookie.
• If you enable Google Places, mention Google in your privacy policy as a recipient of address input for the relevant countries.

Troubleshooting

Suggestions do not appear

• Check that the relevant engine is enabled in the module configuration.
• Check the minimum character setting: suggestions only trigger from the configured threshold.
• Clear the PrestaShop cache (Advanced Parameters → Performance) to force JS/CSS asset reload.
• Open the browser console: a CORS error or blocking by an extension (adblock, privacy protection) can prevent API calls.

Google Places does not trigger

• Check that the selected country is in the allowlist (or that the list is empty).
• Check in the browser console that the Google Maps script loads without error: an invalid key, a disabled API or an overly strict referrer restriction produces an explicit Google Maps JavaScript API error.
• Check that billing is enabled on your Google Cloud project: the Places APIs reject requests without an active billing account.

The city does not fill from the postcode

• This feature only applies to the BAN engine (France) and disables itself if the city field already contains a value typed by the customer.
• Some postcodes cover several municipalities: the module then shows a picker instead of auto-filling.

Conflict with a third-party checkout module

The module targets fields by their standard name attributes (address1, postcode, city, id_country). Third-party one-page checkouts that keep these field names work with no configuration. If a third-party module renames the fields, autocomplete silently disables without breaking the checkout — contact support with the name of the module involved.

FAQ

Does the module slow down my store?

No. The JS and CSS only load on the 4 pages containing an address form, and all autocomplete requests are executed by the customer browser, never by your server.

Can I use only the French API without Google?

Yes, that is the default mode. Google Places is strictly optional and does not load until it is enabled with a valid key.

Does the module work in multi-store?

Yes. Configuration is handled by the native PrestaShop configuration table and respects the standard multi-store context.

What happens on uninstall?

All configuration keys are deleted. Since no table was created, uninstalling leaves no trace.

Changelog

1.0.0 — May 15, 2026

• Initial public release
• French BAN API integrated by default (free, no key)
• Optional Google Places with API key and country allowlist
• Prefill postcode → city → street
• Compatible with PrestaShop 8.0 to 9.x, one-page and multi-step checkout
• Keyboard navigation, match highlighting, configurable debounce
• No template override, no SQL tables