PS PrestaShop Beginner

DataFirefly Address Lookup — Documentation

Installation, settings and troubleshooting of address suggestions: free Géoplateforme service (IGN, BAN data) for France and overseas, optional Google Places API (New) for other countries.

Updated Module version 2.0.0

Overview

DataFirefly Address Lookup suggests addresses while customers type in the PrestaShop address forms: the checkout (customers and guests, delivery and invoice addresses) and My account > My addresses. The customer types the start of the address, picks a suggestion, and the module fills in the street, postcode, city and, for countries that have them, the state or province.

Two providers are available and are chosen country by country:

  • Géoplateforme: geocoding service of the French national mapping agency (IGN) built on the national address database (BAN), data.geopf.fr/geocodage. Free, no key. It replaces api-adresse.data.gouv.fr, decommissioned at the end of January 2026.
  • Google Places API (New): optional, with your own Google Maps Platform key, for the countries the Géoplateforme does not cover.

New in 2.0.0: provider per country, overseas territories served by the Géoplateforme, Google loaded only when it is used, state/province filled in, suggestion list fully usable with the keyboard and screen readers, “Enter my address manually” button, preview and tests in the back office, privacy notice, statistics without personal data, 8 languages, compatibility extended to PrestaShop 1.7.8.

Requirements and compatibility

  • PrestaShop 1.7.8 to 9.x, PHP 7.1 or later.
  • Classic and Hummingbird themes, and themes that keep the standard field names (address1, postcode, city, id_country, id_state). No jQuery needed.
  • Checkout modules that render the standard address form, for instance DataFirefly Simple Checkout.
  • For Google Places only: a Google Cloud key with Places API (New) and Maps JavaScript API enabled and billing active.

Installation and upgrade

  1. In Modules > Module Manager, click Upload a module and drop dfaddresslookup-2.0.0.zip.
  2. Click Configure. Without any other setting, France and the overseas territories get Géoplateforme suggestions.

Upgrade from 1.0.x or 1.1.0: upload the new zip over the old one. Every setting is kept; the 1.x “Allowed countries (Google)” list becomes the per-country provider table, so the same countries keep the same suggestions. The upgrade script also clears PrestaShop’s combined CSS cache, which would otherwise keep serving the old stylesheet.

Module overview

The first tab sums up what customers see: number of countries per provider, pages, privacy notice, detected checkout modules and counters of the last 30 days.

Module overview: countries served by the Géoplateforme and by Google Places, status of the pages and counters of the last 30 days
Module overview

Countries and providers

Each country enabled in the shop has its own choice: Automatic, Géoplateforme, Google Places or No suggestions. In automatic mode, the Géoplateforme serves the countries where it has addresses; for the others, the “Countries the Géoplateforme does not cover” setting picks Google Places (if a key is set) or no suggestions. The Result column updates live.

The Géoplateforme covers metropolitan France, Guadeloupe, Martinique, French Guiana, Réunion, Mayotte, Saint-Pierre-et-Miquelon, Saint-Barthélemy and Saint-Martin, and part of New Caledonia and French Polynesia. It has no data for Wallis-et-Futuna or Monaco. An overseas address typed with the country “France” is found too.

Provider for each country: Géoplateforme for France, Guadeloupe and Réunion, Google Places for the countries it does not cover
Provider for each country

Search settings

  • Minimum characters (2 to 10, default 3; the Géoplateforme needs at least 3).
  • Delay before searching (80 to 2000 ms, default 250): pause after the last key.
  • Number of suggestions (1 to 10, default 6) and time limit (1000 to 15000 ms) after which the search is dropped.
  • Highlight the typed text, city from the postal code, Enter my address manually button.
  • Pages: checkout and/or My addresses. The script is only loaded on these pages, and not at all when no country has a provider. An advanced field accepts the controllers of a checkout module with its own page.
  • Accent colour: empty, the primary colour of the theme is used.
Search settings: minimum characters, delay before searching, number of suggestions, time limit, pages and colour
Search settings

Google Places key

The module only uses Places API (New): the legacy Places Autocomplete widget is no longer offered to new Google Cloud projects. The Google script is only loaded when a customer types an address in a country served by Google.

  1. In the Google Cloud console, create or choose a project with billing enabled.
  2. In APIs & Services, enable Places API (New) and Maps JavaScript API.
  3. Create an API key in Credentials.
  4. Application restrictions: Websites. Add the referrers shown by the module (shop and back-office domains, Copy button).
  5. API restrictions: restrict the key to Places API (New) and Maps JavaScript API.
  6. Paste the key, enable Google Places, save, then click Test the key.

Billing: the module groups the searches of one address in a session token, closed by a single Place Details request limited to the address fields (Essentials category). Google bills this usage to your account according to its current price list; the number of sessions appears in the Statistics tab. By default, only addresses are suggested (street numbers, buildings, streets), not businesses.

A Maps JavaScript key is visible in the pages of the shop: never deploy it without an HTTP referrer restriction.

Google Places API (New) key: activation, addresses only, session billing and steps to restrict the key
Google Places API (New) key

Preview and test

The Preview and test tab reproduces an address form with the current settings, even before saving. The test buttons query the Géoplateforme and Google Places from your browser, as a customer would, and show the response time or the cause of a failure (key refused, network, CSP directive).

Live preview and connection test: Géoplateforme suggestions and Google Places answer from the back office
Live preview and connection test

Customer side

Suggestions and keyboard

Suggestions appear under the Address field, over the page: the form does not move. Each line shows the street, then the postcode, city and region. Up and down arrows browse the list, Enter chooses, Escape closes without clearing the text; the number of suggestions is announced to screen readers.

Address suggestions at checkout: Hôtel de Ville squares with postcode, city and region
Address suggestions at checkout
Keyboard navigation: arrow keys to browse the suggestions, Enter to choose, Escape to close
Keyboard navigation

Filling in the form

Fields are only filled when the customer selects a suggestion, and are briefly highlighted. The second address line is never replaced, and the city from the postal code only fills an empty field. Delivery and invoice forms work independently, and the provider follows the selected country, including when PrestaShop reloads the form.

Form filled after the choice: address, postcode and city highlighted, address complement left as it is
Form filled after the choice

City from the postal code

For countries served by the Géoplateforme, a 5-digit postcode fills the city when only one town matches, or lists the towns when there are several.

Postcode shared by several towns: list of cities under the postcode field
Postcode shared by several towns

No result, error, manual entry

When no address matches, or when the service is slow, saturated (429 response) or unavailable, the list says so and reminds the customer that manual entry stays possible. The Enter my address manually button (or the Escape key) closes the list; the order is never blocked.

No address found: clear message and manual entry button, the order is never blocked
No address found

Google Places for other countries

For a country served by Google, suggestions come from Google Places and carry the “Google Maps” attribution. On selection, the state or province is also chosen in the PrestaShop list when the country has one.

Address in the United States: Google Places (New) suggestions with the Google Maps attribution
Address in the United States

Mobile and My addresses

On phones, lines are at least 48 px high and the list stays inside the screen. The same suggestions are available when a customer adds or edits an address in their account.

On mobile: suggestions under the field, large tap targets and manual entry button
On mobile
My account, My addresses: the same suggestions to add or edit an address
My account, My addresses

Privacy

The text typed in the Address field goes from the customer’s browser to the provider of the country: the Géoplateforme (data.geopf.fr, without cookie) or Google (maps.googleapis.com, only for countries served by Google and only once the customer types). Nothing goes through DataFirefly. A notice is shown under the field, in every language, with the name of the provider ({provider}) and an optional link to a CMS page. This notice informs the customer; it does not replace your own analysis of your obligations.

Notice under the Address field: text per language, link to a page and where the typed data goes
Notice under the Address field

Statistics

The module counts, per day and per provider, the searches, addresses selected, searches without result, errors and Google sessions. No address, IP address or customer identifier is stored. Counting can be turned off and reset.

Usage statistics: searches, addresses selected, no result, errors and Google sessions, without personal data
Usage statistics

Security and Content Security Policy

  • Suggestions are built as text: no provider data is inserted as HTML.
  • The module uses no inline script and no eval, and has no server proxy.
  • If your shop sends a CSP header: connect-src https://data.geopf.fr for the Géoplateforme; for Google, the directives of the Help tab (the page nonce is passed to the Google script when there is one).

Troubleshooting

No suggestion appears

  • Check that the module is enabled and that the page is one of the selected pages.
  • In Countries and providers, check the Result column of the country selected in the form.
  • Run the Géoplateforme test in Preview and test: a failure usually means a network block or a connect-src directive.
  • After a manual file update, clear the cache in Advanced Parameters > Performance.

Google Places does not answer

  • The Test the key button tells whether Google refuses the key: API not enabled, billing inactive or domain missing from the referrers.
  • The back-office domain must be in the referrers for the test and the preview.

A third-party checkout module

Checkouts that keep the standard field names work without any setting. If they have their own page, add their controller in Other controllers. If they rename the fields, entry stays manual, without error.

FAQ

Is a key needed for France?

No. The Géoplateforme is free and needs no key. Google Places is optional.

Is the script loaded on every page?

No: only on the checkout and the address page (depending on your settings), and the Google script only when a customer types in a country served by Google.

What happens on uninstall?

The settings and the statistics table are deleted.

Changelog

2.0.0 — November 8, 2026

  • Provider per country (automatic, Géoplateforme, Google Places, none); overseas territories created as separate countries served by the Géoplateforme
  • Google: script loaded on demand, addresses only, session token closed by an Essentials request, state/province filled in, Google Maps attribution, refused key detected
  • New suggestion list: loading, no result, error and pause states, manual entry button, complete ARIA combobox pattern, mobile sizes
  • Outdated requests cancelled, time limit, cache, pause on 429 responses
  • Back office rebuilt: preview, connection tests, key help, privacy notice, statistics; 8 languages
  • Compatible with PrestaShop 1.7.8 to 9; upgrade from 1.0.x and 1.1.0 keeps every setting

1.1.0 — August 23, 2026

  • Google engine migrated to Places API (New)

1.0.3 and 1.0.2 — August 23, 2026

  • Street kept after selection; list no longer reopens after the choice

1.0.1 — July 1, 2026

  • Switch to the Géoplateforme (data.geopf.fr/geocodage)

1.0.0 — May 15, 2026

  • Initial public release
Was this page helpful?

Still stuck? Contact support