Suggestions d'adresse via Google Places sur des champs de saisie personnalisés

PLUS

L’autocomplétion d’adresses qu’utilise WP-ImmoMakler dans la recherche par rayon est disponible à partir de la version 5.60.0 en tant que bibliothèque réutilisable sur n’importe quel champ de saisie de votre site web. Vous pouvez l’utiliser, par exemple, pour équiper un formulaire de contact, un outil de recherche d’agent immobilier ou un filtre personnalisé avec les mêmes suggestions — navigation au clavier, mise en cache et protection de votre clé API Google incluses.

Prérequis

Pour que la bibliothèque soit active sur une page, les conditions suivantes doivent être remplies :

Vous utilisez l’édition Plus de WP-ImmoMakler.
Les services Google sont activés dans l’interface d’administration WordPress (wp-admin) sous WP-ImmoMakler → Intégrations → Services de géolocalisation et une clé API Google Maps Geocoding valide est renseignée.

Si les deux conditions sont remplies, WP-ImmoMakler charge automatiquement le script assets-plus/js/places-autocomplete.js sur chaque page du frontend (en différé). Si le script ne trouve pas de champ de saisie correspondant sur la page, il n’a aucun autre effet — aucune requête n’est envoyée à Google.

Variante 1 : via attribut HTML (recommandé)

Ajoutez l’attribut data-immomakler-autocomplete à un élément <input>. La bibliothèque détecte automatiquement le champ et s’y attache :

<input
  type="text"
  name="adresse"
  placeholder="Code postal, ville ou rue"
  data-immomakler-autocomplete
  autocomplete="off"
>

Lorsque l’utilisateur sélectionne une suggestion, WP-ImmoMakler insère le texte d’adresse formaté dans le champ et déclenche un CustomEvent nommé immomakler:place-selected sur ce même élément. L’événement contient le texte de l’adresse (label) et l’identifiant Google Place (placeId) dans l’objet detail :

const input = document.querySelector('input[name="adresse"]');
input.addEventListener('immomakler:place-selected', (event) => {
  console.log(event.detail.label);   // "Rue Principale 1, 20095 Hambourg, Allemagne"
  console.log(event.detail.placeId); // "ChIJ..."
});

Variante 2 : via l’API JavaScript

Si le champ de saisie est inséré dynamiquement dans la page (par exemple dans un formulaire ouvert en modal), attachez la bibliothèque explicitement :

const input = document.getElementById('mon-champ-adresse');
window.ImmoMaklerPlacesAutocomplete.attach(input, {
  minLength: 4,        // Nombre minimum de caractères avant la première requête (défaut : 3)
  maxResults: 5,       // Nombre maximum de suggestions (défaut : 8)
  debounceMs: 200      // Délai de frappe en millisecondes (défaut : 140)
});

Pour supprimer le lien — par exemple lors de la fermeture d’un modal — utilisez detach :

window.ImmoMaklerPlacesAutocomplete.detach(input);

attach et detach acceptent aussi bien un élément DOM qu’un sélecteur CSS.

Options par champ de saisie en JSON

Vous pouvez également spécifier les options de la variante 2 directement dans l’attribut data-immomakler-autocomplete au format JSON :

<input
  type="text"
  name="adresse"
  data-immomakler-autocomplete='{"minLength": 4, "maxResults": 5}'
>

Traitement des requêtes

WP-ImmoMakler propose trois moyens pour que le script navigateur récupère les suggestions d’adresse — un rapide et deux qui traversent toute la pile WordPress :

Proxy Fast-API (par défaut, rapide). Un script PHP autonome situé à wp-content/cache/immomakler/fast-api/immomakler-autocomplete.php qui ne charge pas WordPress. Il vérifie un token HMAC signé, effectue une vérification same-origin et une limitation de débit par IP, appelle Google Places via cURL et renvoie du JSON. Une requête prend généralement 5–15 ms au lieu de 100–500 ms (démarrage WordPress avec tous les plugins actifs).
Endpoint REST (solution de repli). POST /wp-json/immomakler/v1/places/autocomplete — passe par index.php, traverse les hooks habituels et renvoie les mêmes suggestions.
Endpoint admin-ajax (deuxième solution de repli). POST /wp-admin/admin-ajax.php?action=immomakler_places_autocomplete — prend le relais lorsque l’API REST n’est pas disponible sur le site (par exemple parce qu’elle a été désactivée par un plugin ou un filtre).

Le script navigateur essaie d’abord la voie 1, puis bascule automatiquement sur la voie 2 et enfin sur la voie 3. Le résultat est fonctionnellement identique pour l’utilisateur final ; seule la latence diffère.

Sessions (jeton de session)

À chaque requête, le script navigateur envoie un jeton de session. Celui-ci regroupe les requêtes d’une même recherche. Mapbox facture les suggestions d’adresse par session. Google recommande également l’usage de sessions, mais ne les facture comme telles que si la session se termine par une requête Place Details. WP-ImmoMakler n’effectue pas une telle requête, c’est pourquoi Google facture chaque requête de suggestion individuellement.

À partir de la version 5.70.0, un jeton est valable pour exactement une recherche : il expire dès que le visiteur sélectionne une suggestion ou envoie le formulaire, ainsi qu’après trois minutes sans requête. La saisie suivante démarre alors une nouvelle session. Le jeton ne réside que dans la mémoire de la page ; chaque chargement de page commence donc avec un nouveau jeton. Jusqu’à la version 5.69, un seul jeton était valable pour toutes les recherches au sein d’un même onglet du navigateur.

Désactiver le proxy Fast-API

Si vos politiques de conformité ou de sécurité exigent qu’aucun fichier PHP en dehors du démarrage WordPress habituel ne soit exécutable, vous pouvez désactiver le proxy Fast-API dans l’interface d’administration WordPress (wp-admin) sous WP-ImmoMakler → Intégrations → Services de géolocalisation à l’aide de la case à cocher Utiliser le proxy Fast-API. L’autocomplétion d’adresses fonctionnera alors exclusivement via l’endpoint REST (avec admin-ajax comme deuxième solution de repli), et le script du proxy sera supprimé du système de fichiers lors de l’enregistrement.

Vous pouvez également bloquer le chemin wp-content/cache/immomakler/fast-api/*.php via une règle serveur (.htaccess, Nginx) — le script le détecte (HTTP 403) et bascule automatiquement sur la solution de repli REST sans qu’aucune modification du plugin ne soit nécessaire.

Limitation des requêtes par visiteur

Les trois voies sont accessibles publiquement, et chaque requête qui n’est pas satisfaite depuis le cache est facturée via votre clé API du service de cartographie. Pour éviter qu’un script automatisé ne fasse grimper votre facture ou n’épuise votre quota, WP-ImmoMakler répond à au maximum 600 requêtes facturées par heure par adresse IP. Les suggestions servies depuis le cache ne comptent pas dans cette limite et continuent d’être délivrées même une fois celle-ci atteinte.

La saisie d’un nom de lieu génère, selon sa longueur, environ 10 à 15 requêtes. La limite correspond donc à plus de 40 recherches complètes par heure depuis la même adresse IP, même si plusieurs visiteurs partagent une adresse, par exemple sur un réseau de bureau.

Une fois la limite atteinte, le serveur répond avec un code HTTP 429. Le script navigateur cesse alors de demander d’autres suggestions sur cette page ; le champ de recherche reste un champ de saisie normal, et la recherche par rayon continue de fonctionner avec le texte déjà saisi. WP-ImmoMakler consigne les requêtes rejetées vers l’endpoint REST et l’endpoint admin-ajax dans son journal de protection anti-spam ; le proxy Fast-API ne charge pas WordPress et ne les consigne pas.

Vous ajustez cette valeur avec le filtre immomakler_places_autocomplete_rate_limit ; 0 désactive la limitation. Il s’applique aux trois voies, y compris au proxy Fast-API :

// Autoriser 1 200 requêtes facturées par adresse IP et par heure :
add_filter( 'immomakler_places_autocomplete_rate_limit', fn () => 1200 );

Si votre site web se trouve derrière un proxy inverse ou un CDN qui transmet chaque requête avec sa propre adresse IP, tous les visiteurs partagent alors une seule et même limite. Dans ce cas, transmettez l’adresse IP réelle du visiteur via le filtre immomakler_rate_limit_client_fingerprint. Le proxy Fast-API ne charge pas WordPress et lit toujours REMOTE_ADDR ; dans ce cas, désactivez-le ou configurez votre serveur web pour que REMOTE_ADDR contienne l’adresse IP du visiteur.

Limitation lors de l’envoi de la recherche par rayon

Lorsqu’un visiteur envoie la recherche par rayon, WP-ImmoMakler convertit le lieu saisi en coordonnées sur le serveur (géocodage). Cette requête est également facturée par le service de géolocalisation choisi via votre clé API, sauf si le lieu est déjà dans le cache. Comme la page de synthèse est accessible publiquement via le paramètre ?center=, une limite propre s’applique également ici : au maximum 100 géocodages facturés par heure par adresse IP.

Une recherche portant sur un nouveau lieu coûte un géocodage ; un nom de lieu ambigu situé en dehors de votre région coûte au maximum trois requêtes. Les lieux déjà recherchés, ainsi que la pagination et le tri, ne sont pas comptabilisés. La limite est donc suffisante pour de nombreux visiteurs partageant une même adresse IP.

Une fois la limite atteinte, la page de synthèse affiche tous les biens immobiliers correspondant aux autres critères de recherche, avec un avis au-dessus des résultats indiquant que la recherche par rayon n’est pas disponible pour le moment. Le lieu saisi reste dans le champ de recherche. Les lieux issus du cache continuent de fonctionner. Les alertes de recherche que WP-ImmoMakler exécute via WP-Cron ne sont pas soumises à cette limite. WP-ImmoMakler ne géocode jamais de saisie de plus de 200 caractères.

Vous ajustez cette valeur avec le filtre immomakler_radius_search_geocode_rate_limit ; 0 désactive la limitation :

// Autoriser 300 géocodages facturés par adresse IP et par heure :
add_filter( 'immomakler_radius_search_geocode_rate_limit', fn () => 300 );

Cette limitation identifie également les visiteurs par leur adresse IP ; la remarque ci-dessus concernant le filtre immomakler_rate_limit_client_fingerprint s’applique également ici.

Compatibilité avec les plugins de mise en cache

La bibliothèque est délibérément conçue pour fonctionner avec des configurations de mise en cache agressive (WP Rocket, W3 Total Cache, LiteSpeed Cache, WP Super Cache, Cloudflare APO) :

Pas de token de sécurité dans le HTML. Avant la version 5.60.0, WP-ImmoMakler inscrivait dans le code source de la page un token valable 15 minutes. Sur les pages mises en cache, ce token était déjà expiré pour le premier visiteur. À partir de la version 5.60.0, le token est récupéré au premier focus sur le champ de saisie via l’endpoint non mis en cache /wp-json/immomakler/v1/places/token.
Solution de repli à plusieurs niveaux. Si le proxy rapide échoue (par exemple parce qu’un token a expiré), la bibliothèque en récupère automatiquement un nouveau et réessaie. Si le proxy reste inaccessible, les requêtes basculent de façon transparente vers l’API REST WordPress et enfin vers admin-ajax. Ce n’est que si la limite de requêtes est atteinte (HTTP 429) que la chaîne s’arrête immédiatement (voir plus haut).

Si votre plugin de mise en cache gère les routes REST de façon inhabituelle, excluez le chemin /wp-json/immomakler/v1/places/* du traitement du cache.

Personnalisation via des filtres

Trois filtres influencent le comportement de la bibliothèque :

// Ne pas insérer le script automatiquement dans le pied de page, mais le charger
// soi-même via wp_enqueue_script( 'immomakler-places-autocomplete' ) sur des pages spécifiques :
add_filter( 'immomakler_places_autocomplete_auto_enqueue', '__return_false' );

// Durée de vie du token (en secondes, défaut 900 = 15 minutes) :
add_filter( 'immomakler_places_token_ttl', fn () => 600 );

// Nombre minimum de caractères / nombre maximum de suggestions / délai de frappe :
add_filter( 'immomakler_places_autocomplete_min_length', fn () => 4 );
add_filter( 'immomakler_places_autocomplete_max_results', fn () => 5 );
add_filter( 'immomakler_places_autocomplete_debounce_ms', fn () => 200 );