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 → Integrationen → Geodienste 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.

Sitzungen (Session-Token)

Mit jeder Anfrage schickt das Browserskript ein Session-Token mit. Es fasst die Anfragen einer Suche zusammen. Mapbox rechnet Adressvorschläge pro Sitzung ab. Google empfiehlt Sitzungen ebenfalls, rechnet sie aber nur dann als Sitzung ab, wenn diese mit einer Place-Details-Anfrage abgeschlossen wird. WP-ImmoMakler stellt keine solche Anfrage, deshalb berechnet Google jede Vorschlagsanfrage einzeln.

Ab Version 5.70.0 gilt ein Token für genau eine Suche: Es endet, sobald der Besucher einen Vorschlag auswählt oder das Formular absendet, und nach drei Minuten ohne Anfrage. Die nächste Eingabe beginnt dann eine neue Sitzung. Das Token liegt nur im Arbeitsspeicher der Seite, jeder Seitenaufruf beginnt also mit einem neuen. Bis Version 5.69 galt ein einziges Token für alle Suchen in einem Browser-Tab.

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 → Integrationen → Geodienste 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.

Begrenzung der Anfragen pro Besucher

Die drei Wege sind öffentlich erreichbar, und jede Anfrage, die nicht aus dem Zwischenspeicher beantwortet wird, rechnet der Kartendienst über Ihren API-Key ab. Damit ein automatisiertes Skript weder Ihre Rechnung in die Höhe treibt noch Ihr Kontingent aufbraucht, beantwortet WP-ImmoMakler pro IP-Adresse höchstens 600 abgerechnete Anfragen pro Stunde. Vorschläge aus dem Zwischenspeicher zählen nicht mit und werden auch danach weiter ausgeliefert.

Beim Eintippen eines Ortsnamens entstehen je nach Länge etwa 10 bis 15 Anfragen. Das Limit entspricht damit mehr als 40 vollständigen Suchen pro Stunde von derselben IP-Adresse, auch wenn sich mehrere Besucher eine Adresse teilen, etwa in einem Büronetz.

Ist das Limit erreicht, antwortet der Server mit HTTP 429. Das Browserskript fragt auf dieser Seite dann keine weiteren Vorschläge ab; das Suchfeld bleibt ein normales Eingabefeld, und die Umkreissuche funktioniert mit dem eingetippten Text weiter. Abgewiesene Anfragen an den REST- und den admin-ajax-Endpunkt hält WP-ImmoMakler in seinem Spam-Schutz-Log fest; der Fast-API-Proxy lädt WordPress nicht und protokolliert sie nicht.

Den Wert passen Sie mit dem Filter immomakler_places_autocomplete_rate_limit an; 0 schaltet die Begrenzung ab. Er gilt für alle drei Wege, auch für den Fast-API-Proxy:

// 1.200 abgerechnete Anfragen pro IP-Adresse und Stunde erlauben:
add_filter( 'immomakler_places_autocomplete_rate_limit', fn () => 1200 );

Steht Ihre Website hinter einem Reverse Proxy oder CDN, der jede Anfrage mit seiner eigenen IP-Adresse weiterreicht, teilen sich alle Besucher ein Limit. Übergeben Sie in diesem Fall über den Filter immomakler_rate_limit_client_fingerprint die tatsächliche Besucher-IP. Der Fast-API-Proxy lädt WordPress nicht und liest stets REMOTE_ADDR; schalten Sie ihn in diesem Fall ab oder stellen Sie Ihren Webserver so ein, dass REMOTE_ADDR die Besucher-IP enthält.

Begrenzung beim Absenden der Umkreissuche

Sendet ein Besucher die Umkreissuche ab, rechnet WP-ImmoMakler den eingegebenen Ort auf dem Server in Koordinaten um (Geocodierung). Diese Abfrage stellt der gewählte Geodienst ebenfalls über Ihren API-Key in Rechnung, sofern der Ort nicht bereits im Zwischenspeicher liegt. Weil die Übersichtsseite mit dem Parameter ?center= öffentlich aufrufbar ist, gilt auch hier eine eigene Begrenzung: pro IP-Adresse höchstens 100 abgerechnete Geocodierungen pro Stunde.

Eine Suche nach einem neuen Ort kostet eine Geocodierung, bei einem mehrdeutigen Ortsnamen außerhalb Ihrer Region höchstens drei Abfragen. Orte, nach denen bereits gesucht wurde, sowie Blättern und Sortieren zählen nicht mit. Das Limit reicht damit für viele Besucher, die sich eine IP-Adresse teilen.

Ist das Limit erreicht, zeigt die Übersichtsseite alle Immobilien, die zu den übrigen Suchkriterien passen, und oberhalb der Ergebnisse einen Hinweis, dass die Umkreissuche im Moment nicht verfügbar ist. Der eingegebene Ort bleibt im Suchfeld stehen. Orte aus dem Zwischenspeicher funktionieren weiterhin. Suchaufträge, die WP-ImmoMakler per WP-Cron ausführt, unterliegen der Begrenzung nicht. Eingaben mit mehr als 200 Zeichen geocodiert WP-ImmoMakler grundsätzlich nicht.

Den Wert passen Sie mit dem Filter immomakler_radius_search_geocode_rate_limit an; 0 schaltet die Begrenzung ab:

// 300 abgerechnete Geocodierungen pro IP-Adresse und Stunde erlauben:
add_filter( 'immomakler_radius_search_geocode_rate_limit', fn () => 300 );

Auch diese Begrenzung erkennt Besucher an ihrer IP-Adresse; der Hinweis zum Filter immomakler_rate_limit_client_fingerprint oben gilt entsprechend.

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. Nur wenn das Anfragen-Limit erreicht ist (HTTP 429), endet die Kette sofort (siehe oben).

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 );