Adressvorschläge per Google Places auf eigenen Eingabefeldern

PLUS

Die Adressvervollständigung, die WP-ImmoMakler in der Umkreissuche einsetzt, steht Ihnen ab Version 5.60.0 als wiederverwendbare Bibliothek auf jedem beliebigen Eingabefeld Ihrer Website zur Verfügung. Sie können damit zum Beispiel ein Kontaktformular, einen Maklerfinder oder einen eigenen Filter mit denselben Vorschlägen ausstatten – inklusive Tastatur-Navigation, Caching und Schutz Ihres Google-API-Schlüssels.

Voraussetzungen

Damit die Bibliothek auf einer Seite aktiv wird, müssen folgende Voraussetzungen erfüllt sein:

Sie nutzen die Plus-Edition von WP-ImmoMakler.
Die Google-Dienste sind im Backend Ihrer Website (wp-admin) unter WP-ImmoMakler → Einstellungen → Google Maps aktiviert und ein gültiger Google Maps Geocoding API Key ist hinterlegt.

Sind beide Bedingungen erfüllt, lädt WP-ImmoMakler das Skript assets-plus/js/places-autocomplete.js auf jeder Frontend-Seite automatisch nach (defer). Findet das Skript dort kein passendes Eingabefeld, hat es keine weitere Wirkung – es entstehen also keine Anfragen an Google.

Variante 1: per HTML-Attribut (empfohlen)

Setzen Sie auf einem <input>-Element das Attribut data-immomakler-autocomplete. Die Bibliothek erkennt das Feld automatisch und hängt sich an:

<input
  type="text"
  name="adresse"
  placeholder="PLZ, Ort oder Straße"
  data-immomakler-autocomplete
  autocomplete="off"
>

Wählt der Nutzer einen Vorschlag aus, übernimmt WP-ImmoMakler den formatierten Adresstext in das Feld und löst auf demselben Element ein CustomEvent mit dem Namen immomakler:place-selected aus. Das Event enthält im detail-Objekt den Adresstext (label) und die Google-Place-ID (placeId):

const input = document.querySelector('input[name="adresse"]');
input.addEventListener('immomakler:place-selected', (event) => {
  console.log(event.detail.label);   // "Hauptstraße 1, 20095 Hamburg, Deutschland"
  console.log(event.detail.placeId); // "ChIJ..."
});

Variante 2: per JavaScript-API

Wenn das Eingabefeld dynamisch in die Seite eingefügt wird (zum Beispiel in einem modal geöffneten Formular), binden Sie die Bibliothek explizit an:

const input = document.getElementById('mein-adressfeld');
window.ImmoMaklerPlacesAutocomplete.attach(input, {
  minLength: 4,        // Mindestanzahl Zeichen vor erstem Request (Default: 3)
  maxResults: 5,       // Maximale Anzahl Vorschläge (Default: 8)
  debounceMs: 200      // Tippverzögerung in Millisekunden (Default: 140)
});

Zum Lösen der Bindung – etwa beim Schließen eines Modals – verwenden Sie detach:

window.ImmoMaklerPlacesAutocomplete.detach(input);

attach und detach akzeptieren wahlweise ein DOM-Element oder einen CSS-Selektor.

Optionen pro Eingabefeld als JSON

Sie können die Optionen aus Variante 2 auch direkt im data-immomakler-autocomplete-Attribut als JSON hinterlegen:

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

Wie die Anfragen verarbeitet werden

WP-ImmoMakler stellt drei Wege bereit, über die das Browserskript die Adressvorschläge holt – einen schnellen und zwei, die den vollen WordPress-Stack durchlaufen:

Fast-API-Proxy (Standard, schnell). Ein eigenständiges PHP-Skript unter wp-content/cache/immomakler/fast-api/immomakler-autocomplete.php, das WordPress nicht mitlädt. Es prüft ein signiertes HMAC-Token, einen Same-Origin-Check und ein Rate-Limit pro IP, ruft Google Places per cURL auf und liefert JSON zurück. Eine Anfrage kostet typischerweise 5–15 ms statt 100–500 ms (WordPress-Bootstrap mit allen aktiven Plugins).
REST-Endpunkt (Fallback). POST /wp-json/immomakler/v1/places/autocomplete – läuft über index.php, durchläuft die regulären Hooks, liefert dieselben Vorschläge.
admin-ajax-Endpunkt (zweiter Fallback). POST /wp-admin/admin-ajax.php?action=immomakler_places_autocomplete – greift, wenn die REST-API auf der Website nicht verfügbar ist (etwa weil sie per Plugin oder Filter abgeschaltet wurde).

Das Browserskript versucht zuerst Pfad 1, fällt automatisch auf Pfad 2 und schließlich auf Pfad 3 zurück. Funktional ist das für den Endnutzer identisch, nur die Latenz unterscheidet sich.

Fast-API deaktivieren

Wenn Ihre Compliance- oder Sicherheitsrichtlinien verlangen, dass keine PHP-Dateien außerhalb des regulären WordPress-Bootstraps ausführbar sind, können Sie den Fast-API-Proxy im Backend Ihrer Website (wp-admin) unter WP-ImmoMakler → Einstellungen → Google Maps mit der Checkbox Fast-API-Proxy verwenden abschalten. Die Adressvervollständigung läuft dann ausschließlich über den REST-Endpunkt (mit admin-ajax als zweitem Fallback); das Proxy-Skript wird beim Speichern aus dem Dateisystem entfernt.

Alternativ können Sie den Pfad wp-content/cache/immomakler/fast-api/*.php per Server-Regel (.htaccess, Nginx) blockieren – das Skript erkennt das (HTTP 403) und schaltet automatisch auf den REST-Fallback um, ohne dass im Plugin etwas geändert werden muss.

Kompatibilität mit Caching-Plugins

Die Bibliothek ist bewusst so gebaut, dass sie mit aggressiv cachenden Setups (WP Rocket, W3 Total Cache, LiteSpeed Cache, WP Super Cache, Cloudflare APO) zusammenarbeitet:

Kein Sicherheits-Token im HTML. Vor Version 5.60.0 hat WP-ImmoMakler einen 15 Minuten gültigen Token in den Quellcode der Seite geschrieben. Bei gecachten Seiten war dieser Token bereits beim ersten Besucher abgelaufen. Ab 5.60.0 wird der Token erst beim ersten Fokus auf das Eingabefeld über den nicht-cachebaren Endpunkt /wp-json/immomakler/v1/places/token geholt.
Mehrstufiger Fallback. Schlägt der schnelle Proxy fehl (etwa weil ein Token abgelaufen ist), holt sich die Bibliothek automatisch einen neuen und versucht es erneut. Antwortet der Proxy weiterhin nicht, fallen die Anfragen transparent auf die WordPress-REST-API und schließlich auf admin-ajax zurück. Die Adressvervollständigung funktioniert in jedem Fall.

Falls Ihr Caching-Plugin REST-Routen ungewöhnlich behandelt, schließen Sie den Pfad /wp-json/immomakler/v1/places/* von der Cache-Verarbeitung aus.

Anpassung per Filter

Drei Filter beeinflussen das Verhalten der Bibliothek:

// Skript nicht automatisch in den Footer einfügen, sondern selbst per
// wp_enqueue_script( 'immomakler-places-autocomplete' ) auf bestimmten
// Seiten laden:
add_filter( 'immomakler_places_autocomplete_auto_enqueue', '__return_false' );

// Lebensdauer des Tokens (in Sekunden, Standard 900 = 15 Minuten):
add_filter( 'immomakler_places_token_ttl', fn () => 600 );

// Mindestanzahl Zeichen / maximale Vorschläge / Tippverzögerung:
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 );