# 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…

- Page: <https://www.datafirefly.com/en/documentation/dfaddresslookup/>
- Language: en
- Last updated: 2026-08-25
- Other languages: [fr](https://www.datafirefly.com/documentation/dfaddresslookup/index.md), [es](https://www.datafirefly.com/es/documentation/dfaddresslookup/index.md), [de](https://www.datafirefly.com/de/documentation/dfaddresslookup/index.md), [it](https://www.datafirefly.com/it/documentation/dfaddresslookup/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfaddresslookup/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfaddresslookup/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfaddresslookup/index.md)
- Index: <https://www.datafirefly.com/en/documentation/llms.txt>

## 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 (data.geopf.fr/geocodage), 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.

**No data transits through your server or through DataFirefly.** Requests go directly from the customer browser to the BAN API or Google Places. The module creates no SQL table and overrides no Smarty template.

## 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 (New)_ 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 data.geopf.fr/geocodage 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](https://console.cloud.google.com/) and select or create a project.
2. In **APIs & Services → Library**, enable **Places API (New)** 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 (New) and Maps JavaScript API.
5. Paste the key into the module configuration and save.

Never deploy a Google key without HTTP referrer restriction: it could be used by any third-party site and generate billing at your expense.

## 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.1.0 — August 23, 2026

- Migrated the Google engine to Places API (New): programmatic AutocompleteSuggestion API with session tokens and Place.fetchFields; the legacy widget is unavailable to new Google Cloud customers since March 2025
- Google suggestions render in the module's own dropdown: unified UX, keyboard navigation, highlighting, restriction to the selected country
- France can be fully served by Google Places by disabling the BAN engine

### 1.0.3 — August 23, 2026

- Fixed: on some themes, a third-party script restored the typed text into the street field after selecting a suggestion, leaving the address unfilled; the street is now written last and its value re-asserted if overwritten
- Dropdown re-opening protection now uses a time window

### 1.0.2 — August 23, 2026

- Fixed: the suggestion dropdown stayed open after selecting an address, as the search was re-triggered by the synthetic events fired while filling the fields

### 1.0.1 — July 1, 2026

- Migrated the French engine to the Géoplateforme geocoding service (data.geopf.fr/geocodage, IGN), as the legacy api-adresse.data.gouv.fr endpoint was decommissioned end of January 2026
- Iso-functional API: same parameters, same GeoJSON response, same 50 requests per second per IP limit
- Updated back-office labels and suggestion attribution

### 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