PS PrestaShop Débutant

DataFirefly Address Lookup — Documentation

Installation, réglages et dépannage des suggestions d'adresse : Géoplateforme (IGN, données BAN) gratuite pour la France et l'outre-mer, Google Places API (New) en option pour les autres pays.

Mis à jour Version du module 2.0.0

Présentation

DataFirefly Address Lookup propose des adresses pendant la saisie dans les formulaires d’adresse de PrestaShop : tunnel de commande (clients et invités, adresse de livraison et adresse de facturation) et Mon compte > Mes adresses. Le client tape le début de son adresse, choisit une suggestion, et le module remplit la rue, le code postal, la ville et, pour les pays qui en ont, l’État ou la province.

Deux fournisseurs sont disponibles et se choisissent pays par pays :

  • Géoplateforme : service de géocodage de l’IGN construit sur la Base Adresse Nationale (BAN), data.geopf.fr/geocodage. Gratuit, sans clé. Il remplace api-adresse.data.gouv.fr, décommissionnée fin janvier 2026.
  • Google Places API (New) : en option, avec votre propre clé Google Maps Platform, pour les pays que la Géoplateforme ne couvre pas.

Nouveautés 2.0.0 : fournisseur par pays, outre-mer servi par la Géoplateforme, Google chargé uniquement quand il sert, État/province rempli, liste de suggestions entièrement accessible au clavier et aux lecteurs d’écran, bouton « Saisir mon adresse manuellement », aperçu et tests dans le back-office, mention de confidentialité, statistiques sans donnée personnelle, 8 langues, compatibilité étendue à PrestaShop 1.7.8.

Prérequis et compatibilité

  • PrestaShop 1.7.8 à 9.x, PHP 7.1 ou supérieur.
  • Thèmes Classic et Hummingbird, et les thèmes qui gardent les noms de champs standard (address1, postcode, city, id_country, id_state). jQuery n’est pas nécessaire.
  • Modules de checkout qui affichent le formulaire d’adresse standard, par exemple DataFirefly Simple Checkout.
  • Pour Google Places uniquement : une clé Google Cloud avec Places API (New) et Maps JavaScript API activées et la facturation active.

Installation et mise à jour

  1. Dans Modules > Gestionnaire de modules, cliquez sur Installer un module et déposez dfaddresslookup-2.0.0.zip.
  2. Cliquez sur Configurer. Sans autre réglage, la France et les territoires d’outre-mer reçoivent les suggestions de la Géoplateforme.

Mise à jour depuis la 1.0.x ou la 1.1.0 : déposez le nouveau zip par-dessus l’ancien. Tous les réglages sont conservés ; la liste « Pays autorisés (Google) » de la 1.x devient la table des fournisseurs par pays, de sorte que les mêmes pays gardent les mêmes suggestions. Le script de mise à jour vide aussi le cache CSS combiné de PrestaShop, qui sinon continuerait de servir l’ancienne feuille de style.

Vue d’ensemble

Le premier onglet résume ce que voient les clients : nombre de pays servis par chaque fournisseur, pages concernées, mention de confidentialité, modules de checkout détectés et compteurs des 30 derniers jours.

Vue d'ensemble du module : pays servis par la Géoplateforme et par Google Places, état des pages et compteurs des 30 derniers jours
Vue d’ensemble du module

Pays et fournisseurs

Chaque pays activé dans la boutique a son propre choix : Automatique, Géoplateforme, Google Places ou Pas de suggestions. En automatique, la Géoplateforme sert les pays où elle a des adresses ; pour les autres, le réglage « Pays non couverts par la Géoplateforme » choisit Google Places (si une clé est renseignée) ou aucune suggestion. La colonne Résultat se met à jour en direct.

La Géoplateforme couvre la France métropolitaine, la Guadeloupe, la Martinique, la Guyane, La Réunion, Mayotte, Saint-Pierre-et-Miquelon, Saint-Barthélemy et Saint-Martin, ainsi qu’une partie de la Nouvelle-Calédonie et de la Polynésie française. Elle n’a pas de données pour Wallis-et-Futuna ni Monaco. Une adresse d’outre-mer saisie avec le pays « France » est aussi trouvée.

Fournisseur pour chaque pays : Géoplateforme pour la France, la Guadeloupe et La Réunion, Google Places pour les pays non couverts
Fournisseur pour chaque pays

Réglages de saisie

  • Nombre minimal de caractères (2 à 10, 3 par défaut ; la Géoplateforme en demande au moins 3).
  • Délai avant la recherche (80 à 2000 ms, 250 par défaut) : pause après la dernière touche.
  • Nombre de suggestions (1 à 10, 6 par défaut) et délai maximal (1000 à 15000 ms) au-delà duquel la recherche est abandonnée.
  • Surligner le texte saisi, ville à partir du code postal, bouton Saisir mon adresse manuellement.
  • Pages : tunnel de commande et/ou Mes adresses. Le script n’est chargé que sur ces pages, et pas du tout si aucun pays n’a de fournisseur. Un champ avancé accepte les contrôleurs d’un module de checkout qui a sa propre page.
  • Couleur d’accent : vide, la couleur principale du thème est utilisée.
Réglages de saisie : caractères minimum, délai avant recherche, nombre de suggestions, délai maximal, pages et couleur
Réglages de saisie

Clé Google Places

Le module utilise uniquement Places API (New) : l’ancien widget Places Autocomplete n’est plus proposé aux nouveaux projets Google Cloud. Le script Google n’est chargé qu’au moment où un client tape une adresse dans un pays servi par Google.

  1. Dans la console Google Cloud, créez ou choisissez un projet avec la facturation activée.
  2. Dans API et services, activez Places API (New) et Maps JavaScript API.
  3. Créez une clé d’API dans Identifiants.
  4. Restrictions relatives aux applications : Sites Web. Ajoutez les référents affichés par le module (domaines de la boutique et du back-office, bouton Copier).
  5. Restrictions d’API : limitez la clé à Places API (New) et Maps JavaScript API.
  6. Collez la clé, activez Google Places, enregistrez, puis cliquez sur Tester la clé.

Facturation : le module regroupe les recherches d’une même adresse dans un jeton de session, clos par une seule requête Place Details limitée aux champs d’adresse (catégorie Essentials). Google facture cet usage sur votre compte selon sa grille en vigueur ; le nombre de sessions apparaît dans l’onglet Statistiques. Par défaut, seules les adresses sont proposées (numéros, bâtiments, rues), pas les commerces.

Une clé Maps JavaScript est visible dans les pages de la boutique : ne la déployez jamais sans restriction de référent HTTP.

Clé Google Places API (New) : activation, adresses uniquement, facturation par session et étapes pour restreindre la clé
Clé Google Places API (New)

Aperçu et test

L’onglet Aperçu et test reproduit un formulaire d’adresse avec les réglages en cours, même avant l’enregistrement. Les boutons de test interrogent la Géoplateforme et Google Places depuis votre navigateur, comme le ferait un client, et indiquent le temps de réponse ou la cause d’un échec (clé refusée, réseau, directive CSP).

Aperçu interactif et test de connexion : suggestions de la Géoplateforme et réponse de Google Places depuis le back-office
Aperçu interactif et test de connexion

Côté client

Suggestions et clavier

Les suggestions s’affichent sous le champ Adresse, par-dessus la page : le formulaire ne bouge pas. Chaque ligne montre la rue, puis le code postal, la ville et la région. Les flèches haut et bas parcourent la liste, Entrée choisit, Échap ferme sans effacer la saisie ; le nombre de suggestions est annoncé aux lecteurs d’écran.

Suggestions d'adresse au checkout : places de l'Hôtel de Ville avec code postal, ville et région
Suggestions d’adresse au checkout
Navigation au clavier : flèches pour parcourir les suggestions, Entrée pour choisir, Échap pour fermer
Navigation au clavier

Remplissage du formulaire

Les champs ne sont remplis que lorsque le client choisit une suggestion. Les champs remplis sont brièvement mis en évidence. Le complément d’adresse n’est jamais remplacé, et la ville issue du code postal ne remplit qu’un champ vide. Les formulaires de livraison et de facturation fonctionnent indépendamment, et le fournisseur suit le pays choisi, y compris quand PrestaShop recharge le formulaire.

Formulaire rempli après le choix : adresse, code postal et ville mis en évidence, complément laissé tel quel
Formulaire rempli après le choix

Ville à partir du code postal

Pour les pays servis par la Géoplateforme, un code postal à 5 chiffres remplit la ville quand une seule commune correspond, ou affiche la liste des communes quand il y en a plusieurs.

Code postal partagé par plusieurs communes : liste des villes sous le champ Code postal
Code postal partagé par plusieurs communes

Aucun résultat, erreur, saisie manuelle

Quand aucune adresse ne correspond, quand le service est lent, saturé (réponse 429) ou indisponible, la liste l’indique et rappelle que la saisie manuelle reste possible. Le bouton Saisir mon adresse manuellement (ou la touche Échap) ferme la liste ; la commande n’est jamais bloquée.

Aucune adresse trouvée : message clair et bouton de saisie manuelle, la commande n’est jamais bloquée
Aucune adresse trouvée

Google Places pour les autres pays

Pour un pays servi par Google, les suggestions viennent de Google Places et portent la mention « Google Maps ». À la sélection, l’État ou la province est aussi choisi dans la liste de PrestaShop quand le pays en a.

Adresse aux États-Unis : suggestions Google Places (New) avec l’attribution Google Maps
Adresse aux États-Unis

Mobile et Mes adresses

Sur téléphone, les lignes font au moins 48 px de haut et la liste reste dans l’écran. Les mêmes suggestions sont disponibles quand un client ajoute ou modifie une adresse dans son compte.

Sur mobile : suggestions sous le champ, grandes zones de tap et bouton de saisie manuelle
Sur mobile
Mon compte, Mes adresses : les mêmes suggestions pour ajouter ou modifier une adresse
Mon compte, Mes adresses

Confidentialité

Le texte saisi dans le champ Adresse part du navigateur du client vers le fournisseur du pays : la Géoplateforme (data.geopf.fr, sans cookie) ou Google (maps.googleapis.com, seulement pour les pays servis par Google et seulement quand le client tape). Rien ne transite par DataFirefly. Une mention s’affiche sous le champ, dans chaque langue, avec le nom du fournisseur ({provider}) et un lien facultatif vers une page CMS. Cette mention informe le client ; elle ne remplace pas votre propre analyse de vos obligations.

Mention sous le champ Adresse : texte par langue, lien vers une page et destination des données saisies
Mention sous le champ Adresse

Statistiques

Le module compte, par jour et par fournisseur, les recherches, les adresses choisies, les recherches sans résultat, les erreurs et les sessions Google. Aucune adresse, adresse IP ou identifiant client n’est enregistré. Le comptage peut être désactivé et remis à zéro.

Statistiques d'utilisation : recherches, adresses choisies, aucun résultat, erreurs et sessions Google, sans donnée personnelle
Statistiques d’utilisation

Sécurité et Content Security Policy

  • Les suggestions sont construites comme du texte : aucune donnée de fournisseur n’est insérée comme HTML.
  • Le module n’utilise ni script inline ni eval et n’a pas de proxy serveur.
  • Si votre boutique envoie un en-tête CSP : connect-src https://data.geopf.fr pour la Géoplateforme ; pour Google, les directives de l’onglet Aide (le nonce de la page est transmis au script Google quand il existe).

Dépannage

Aucune suggestion n’apparaît

  • Vérifiez que le module est activé et que la page fait partie des pages choisies.
  • Dans l’onglet Pays et fournisseurs, vérifiez la colonne Résultat du pays sélectionné dans le formulaire.
  • Lancez le test Géoplateforme de l’onglet Aperçu et test : un échec indique en général un blocage réseau ou une directive connect-src.
  • Après une mise à jour manuelle des fichiers, videz le cache dans Paramètres avancés > Performances.

Google Places ne répond pas

  • Le bouton Tester la clé indique si Google refuse la clé : API non activée, facturation inactive ou domaine absent des référents.
  • Le domaine du back-office doit figurer dans les référents pour le test et l’aperçu.

Un module de checkout tiers

Les checkouts qui gardent les noms de champs standard fonctionnent sans réglage. S’ils ont leur propre page, ajoutez leur contrôleur dans Autres contrôleurs. S’ils renomment les champs, la saisie reste manuelle, sans erreur.

FAQ

Faut-il une clé pour la France ?

Non. La Géoplateforme est gratuite et sans clé. Google Places est optionnel.

Le script est-il chargé sur toutes les pages ?

Non : seulement sur le tunnel de commande et la page d’adresse (selon vos réglages), et le script Google seulement quand un client tape dans un pays servi par Google.

Que se passe-t-il à la désinstallation ?

Les réglages et la table des statistiques sont supprimés.

Changelog

2.0.0 — 8 novembre 2026

  • Fournisseur par pays (automatique, Géoplateforme, Google Places, aucun) ; territoires d’outre-mer créés comme pays distincts servis par la Géoplateforme
  • Google : script chargé à la demande, adresses uniquement, jeton de session clos par une requête Essentials, État/province rempli, attribution Google Maps, détection d’une clé refusée
  • Nouvelle liste de suggestions : états chargement, aucun résultat, erreur et pause, bouton de saisie manuelle, pattern ARIA combobox complet, tailles mobiles
  • Requêtes annulées quand elles deviennent obsolètes, délai maximal, cache, pause sur réponse 429
  • Back-office refait : aperçu, tests de connexion, aide pour la clé, mention de confidentialité, statistiques ; 8 langues
  • Compatibilité PrestaShop 1.7.8 à 9 ; mise à jour depuis la 1.0.x et la 1.1.0 sans perte de réglages

1.1.0 — 23 août 2026

  • Moteur Google migré vers Places API (New)

1.0.3 et 1.0.2 — 23 août 2026

  • Rue conservée après la sélection ; liste qui ne se rouvre plus après le choix

1.0.1 — 1 juillet 2026

  • Passage à la Géoplateforme (data.geopf.fr/geocodage)

1.0.0 — 15 mai 2026

  • Première version publique
Cette page vous a-t-elle été utile ?

Toujours bloqué ? Contactez le support