# DataFirefly Address Lookup — Documentation

> Présentation DataFirefly Address Lookup ajoute l'autocomplétion d'adresse aux formulaires de PrestaShop 8 et 9 : tunnel de commande, page « Mon adresse », page « Mes informations » et formulaire…

- Page: <https://www.datafirefly.com/documentation/dfaddresslookup/>
- Langue: fr
- Mis à jour le: 2026-08-25
- Autres langues: [en](https://www.datafirefly.com/en/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/documentation/llms.txt>

## Présentation

DataFirefly Address Lookup ajoute l'autocomplétion d'adresse aux formulaires de PrestaShop 8 et 9 : tunnel de commande, page « Mon adresse », page « Mes informations » et formulaire d'inscription. Le module s'appuie sur deux moteurs : l'API française BAN (data.geopf.fr/geocodage), gratuite et sans clé, activée par défaut pour la France, et Google Places en option pour les adresses internationales.

Le workflow côté client est simple : il saisit son code postal, la ville se remplit automatiquement (ou un sélecteur de communes s'affiche si plusieurs correspondent) ; il commence à taper sa rue, les suggestions apparaissent ; un clic remplit d'un coup la rue, le code postal et la ville avec une adresse normalisée.

**Aucune donnée ne transite par votre serveur ni par DataFirefly.** Les requêtes partent directement du navigateur du client vers l'API BAN ou Google Places. Le module ne crée aucune table SQL et ne surcharge aucun template Smarty.

## Prérequis

- PrestaShop 8.0 à 9.x (thème Classic, Hummingbird ou la plupart des thèmes tiers)
- PHP 7.4 ou supérieur
- Pour Google Places uniquement : une clé d'API Google Cloud avec les APIs _Places API (New)_ et _Maps JavaScript API_ activées

## Installation

1. Dans le back-office PrestaShop, ouvrez **Modules → Gestionnaire de modules**.
2. Cliquez sur **Installer un module** et déposez le fichier `dfaddresslookup.zip`.
3. PrestaShop installe le module et enregistre automatiquement les hooks `actionFrontControllerSetMedia` et `displayHeader`.
4. Cliquez sur **Configurer** pour ouvrir l'écran de réglages.

Dès l'installation, l'autocomplétion est active pour la France sans aucune configuration : l'API BAN est activée par défaut et ne nécessite pas de clé.

## Configuration

### API française BAN

**Activer l'API BAN française** — active ou désactive le moteur français. Activé par défaut. L'API data.geopf.fr/geocodage est un service public gratuit : pas de clé, pas d'abonnement, limite indicative de 50 requêtes par seconde et par IP, très au-delà des besoins d'un checkout.

**Pré-remplir la ville depuis le code postal** — quand le client saisit un code postal français à 5 chiffres, la ville se remplit automatiquement si une seule commune correspond ; sinon un sélecteur de communes s'affiche sous le champ. Le module ne remplace jamais une ville déjà saisie par le client.

### Google Places (optionnel)

**Activer Google Places** — active le moteur international. Nécessite une clé d'API valide, sans quoi l'enregistrement de la configuration est refusé.

**Clé d'API Google** — votre clé Google Cloud. Voir la section suivante pour la créer et la sécuriser.

**Pays autorisés** — liste de codes ISO 3166-1 alpha-2 séparés par des virgules (ex. `BE,CH,LU,DE`). Google Places ne se déclenche que pour ces pays ; champ vide = tous les pays. C'est le levier principal pour maîtriser votre facturation Google Cloud.

### Comportement

**Caractères minimum** — nombre de caractères avant le déclenchement des suggestions (2 à 10, défaut 3).

**Debounce (ms)** — délai entre la dernière frappe et l'appel API (80 à 2000 ms, défaut 250). Augmentez-le pour réduire le nombre de requêtes, diminuez-le pour des suggestions plus réactives.

**Surligner les correspondances** — met en gras le texte tapé par le client dans chaque suggestion.

## Obtenir une clé Google Places

1. Ouvrez la [Google Cloud Console](https://console.cloud.google.com/) et sélectionnez ou créez un projet.
2. Dans **APIs & Services → Bibliothèque**, activez **Places API (New)** et **Maps JavaScript API**.
3. Dans **APIs & Services → Identifiants**, créez une **clé d'API**.
4. Restreignez la clé : _Restrictions relatives aux applications_ → « Référents HTTP » → ajoutez votre domaine (ex. `*.maboutique.fr/*`) ; _Restrictions relatives aux API_ → limitez à Places API (New) et Maps JavaScript API.
5. Collez la clé dans la configuration du module et enregistrez.

Ne déployez jamais une clé Google sans restriction de référent HTTP : elle serait utilisable par n'importe quel site tiers et pourrait générer une facturation à votre charge.

## Fonctionnement technique

### Bascule automatique entre moteurs

Le module lit le pays sélectionné dans le champ `id_country` du formulaire. France → moteur BAN. Autre pays présent dans la liste des pays autorisés → Google Places. Pays hors liste ou aucun moteur applicable → l'autocomplétion se désactive silencieusement et le formulaire reste un formulaire de saisie classique. La bascule est immédiate à chaque changement de pays, sans rechargement de page.

### Compatibilité checkout one-page et re-rendus

Le checkout de PrestaShop ré-affiche le formulaire d'adresse à chaque changement d'étape. Le module surveille le DOM avec un `MutationObserver` et s'abonne aux événements natifs `updatedAddressForm`, `updatedAddress`, `updatedDeliveryForm` et `changedCheckoutStep` : l'autocomplétion se ré-attache automatiquement à chaque re-rendu. Chaque formulaire est marqué après liaison pour éviter tout double-attachement.

### Formulaires multiples

Si plusieurs formulaires d'adresse sont affichés simultanément (livraison + facturation), chacun reçoit son propre autocomplete indépendant, avec son propre dropdown et son propre état.

### Navigation clavier et accessibilité

Le dropdown de suggestions se pilote entièrement au clavier : flèches haut/bas pour naviguer, Entrée pour sélectionner, Échap pour fermer. Les suggestions portent les attributs ARIA `role="listbox"` et `role="option"`.

### Dégradation gracieuse

Si l'API est injoignable (panne, client hors ligne, blocage réseau), aucune erreur n'est affichée : le formulaire reste un formulaire de saisie manuelle classique. L'autocomplétion est une amélioration progressive, jamais un point de blocage du checkout.

## RGPD et confidentialité

- Les requêtes d'autocomplétion partent directement du navigateur du client vers l'API BAN (service public français) ou Google Places.
- Aucune donnée ne transite par votre serveur PrestaShop pendant la saisie.
- Aucune donnée ne transite par les serveurs DataFirefly, jamais.
- Le module ne dépose aucun cookie.
- Si vous activez Google Places, mentionnez Google dans votre politique de confidentialité comme destinataire des saisies d'adresse pour les pays concernés.

## Dépannage

### Les suggestions n'apparaissent pas

- Vérifiez que le moteur concerné est activé dans la configuration du module.
- Vérifiez le nombre de caractères minimum : les suggestions ne se déclenchent qu'à partir du seuil configuré.
- Videz le cache PrestaShop (**Paramètres avancés → Performances**) pour forcer le rechargement des assets JS/CSS.
- Ouvrez la console navigateur : une erreur CORS ou un blocage par une extension (adblock, protection vie privée) peut empêcher les appels à l'API.

### Google Places ne se déclenche pas

- Vérifiez que le pays sélectionné figure dans la liste des pays autorisés (ou que la liste est vide).
- Vérifiez dans la console navigateur que le script Google Maps se charge sans erreur : une clé invalide, une API non activée ou une restriction de référent trop stricte produisent une erreur explicite `Google Maps JavaScript API error`.
- Vérifiez que la facturation est activée sur votre projet Google Cloud : les APIs Places refusent les requêtes sans compte de facturation actif.

### La ville ne se remplit pas depuis le code postal

- Cette fonction ne concerne que le moteur BAN (France) et se désactive si le champ ville contient déjà une valeur saisie par le client.
- Certains codes postaux couvrent plusieurs communes : le module affiche alors un sélecteur au lieu de remplir automatiquement.

### Conflit avec un module de checkout tiers

Le module cible les champs par leurs attributs `name` standards (`address1`, `postcode`, `city`, `id_country`). Les checkouts one-page tiers qui conservent ces noms de champs fonctionnent sans configuration. Si un module tiers renomme les champs, l'autocomplétion se désactive silencieusement sans casser le checkout — contactez le support avec le nom du module concerné.

## FAQ

### Le module ralentit-il ma boutique ?

Non. Le JS et le CSS ne sont chargés que sur les 4 pages contenant un formulaire d'adresse, et toutes les requêtes d'autocomplétion sont exécutées par le navigateur du client, jamais par votre serveur.

### Puis-je utiliser uniquement l'API française sans Google ?

Oui, c'est le mode par défaut. Google Places est strictement optionnel et ne se charge pas tant qu'il n'est pas activé avec une clé valide.

### Le module fonctionne-t-il en multi-boutique ?

Oui. La configuration est gérée par la table de configuration native de PrestaShop et respecte le contexte multi-boutique standard.

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

Toutes les clés de configuration sont supprimées. Aucune table n'ayant été créée, la désinstallation ne laisse aucune trace.

## Changelog

### 1.1.0 — 23 août 2026

- Migration du moteur Google vers Places API (New) : API programmatique AutocompleteSuggestion avec session tokens et Place.fetchFields ; le widget legacy n'est plus disponible pour les nouveaux clients Google Cloud depuis mars 2025
- Les suggestions Google s'affichent dans le menu du module : UX unifiée, navigation clavier, surlignage, restriction au pays sélectionné
- La France peut être servie entièrement par Google Places en désactivant le moteur BAN

### 1.0.3 — 23 août 2026

- Correction : sur certains thèmes, un script tiers restaurait le texte saisi dans le champ rue après la sélection d'une suggestion, laissant l'adresse non remplie ; la rue est désormais écrite en dernier et sa valeur ré-assertée si elle est écrasée
- Protection anti-réouverture du menu de suggestions basée sur une fenêtre temporelle

### 1.0.2 — 23 août 2026

- Correction : le menu de suggestions restait ouvert après la sélection d'une adresse, la recherche étant relancée par les événements synthétiques émis lors du remplissage des champs

### 1.0.1 — 1 juillet 2026

- Migration du moteur français vers le service de géocodage Géoplateforme (data.geopf.fr/geocodage, IGN), l'ancien endpoint api-adresse.data.gouv.fr ayant été décommissionné fin janvier 2026
- API iso-fonctionnelle : mêmes paramètres, même réponse GeoJSON, même limite de 50 requêtes par seconde et par IP
- Libellés du back-office et attribution des suggestions mis à jour

### 1.0.0 — 15 mai 2026

- Première version publique
- API française BAN intégrée par défaut (gratuite, sans clé)
- Google Places en option avec clé d'API et liste de pays autorisés
- Pré-remplissage code postal → ville → rue
- Compatible PrestaShop 8.0 à 9.x, checkout one-page et multi-étapes
- Navigation clavier, surlignage des correspondances, debounce configurable
- Aucune surcharge de template, aucune table SQL