Geocoding für TYPO3

Warum jeder TYPO3-Filialfinder ohne Geocoding an der Datenqualität scheitert

Filialfinder, Händlersuche und Umkreissuche haben alle dasselbe Fundament: GPS-Koordinaten. Aber Unternehmen speichern Standortdaten als Adressen - Straße, Hausnummer, PLZ, Stadt. Die Umrechnung von Adresse zu Koordinate (Geocoding) passiert nicht von allein. Eine Geocoding-Extension wie maps2 löst dieses Problem automatisiert: Sie überwacht Adressfelder in TYPO3-Records und berechnet bei jeder Änderung die zugehörigen GPS-Koordinaten über einen Geocoding-Service.

Ohne Geocoding-Extension müssten Redakteure für jeden Standort manuell Breiten- und Längengrad aus Google Maps herauskopieren. Bei 50 Standorten ist das eine Stunde Arbeit. Bei 500 Standorten ein ganzer Arbeitstag - und bei jeder Adressänderung beginnt der Prozess von vorn.

Typische Einsatzszenarien

Automatisches Geocoding für tt_address-Datensätze. Ein Unternehmen mit 120 Standorten in Deutschland, Österreich und der Schweiz pflegt alle Adressen in der TYPO3-Extension tt_address. maps2 bindet die tt_address-Tabelle über seine Registry an und reagiert per DataHandler-Hook auf jede Speicherung. Sobald ein Redakteur eine Adresse ändert oder einen neuen Standort anlegt, wird im Hintergrund der Geocoding-Service aufgerufen. maps2 speichert die Koordinaten in einem eigenen Ortsdatensatz, den es mit der Adresse verknüpft, und platziert daraus den Marker an der richtigen Stelle.

Batch-Geocoding bei Datenmigrationen. Ein Unternehmen migriert 2.000 Adressen aus einem alten System nach TYPO3. Die importierten Datensätze haben Straße und PLZ, aber keine Koordinaten. tt_address bringt dafür den CLI-Command ttaddress:geocode mit, der alle Datensätze ohne Koordinaten in einem Batch-Lauf über die Google Geocoding API geocodiert. Bei der Google Geocoding API liegt das kostenlose Kontingent bei 10.000 Requests pro Monat - für eine einmalige Migration mehr als ausreichend.

Umkreissuche auf Basis von Postleitzahlen. Ein Handwerksbetrieb bietet Umkreissuche an: “Finde den nächsten Partner in deiner Nähe.” Der Besucher gibt seine PLZ ein, ein Geocoding-Service wandelt die PLZ in Koordinaten um, und eine SQL-Distanz-Berechnung (Haversine-Formel) liefert alle Standorte im Radius von 25, 50 oder 100 km, sortiert nach Entfernung.

Technische Architektur

maps2 integriert sich als DataHandler-Hook in den TYPO3 Core. Die Extension überwacht die Tabellen und Adressfelder, die per TCA an ihre Registry angebunden sind. Wenn sich ein überwachtes Adressfeld ändert, löst maps2 beim Speichern einen Geocoding-Request aus.

Die Extension unterstützt zwei Geocoding-Provider:

• Google Geocoding API: Hohe Genauigkeit, weltweit verfügbar, erfordert API-Key mit aktiviertem Billing. Kosten: 5 USD pro 1.000 Requests, kostenlos bis 10.000/Monat (seit März 2025 statt des früheren Guthabens von 200 USD). Vorteil: Verarbeitet auch unvollständige oder fehlerhafte Adressen intelligent.
• OpenStreetMap Nominatim: Kostenlos, keine Registrierung nötig. Einschränkungen: Maximale Abfragerate von 1 Request/Sekunde, Nutzungsbedingungen erfordern einen benutzerdefinierten User-Agent. Genauigkeit in ländlichen Gebieten teilweise geringer als Google.

Die Koordinaten speichert maps2 im eigenen Ortsdatensatz in den Feldern latitude und longitude, tt_address in gleichnamigen Dezimalfeldern. Die Extension kann über TCA-Konfiguration auf jede beliebige Tabelle angewendet werden, nicht nur auf tt_address.

Für die Umkreissuche berechnet maps2 die Entfernung per SQL-Formel im QueryBuilder; eine Haversine-Funktion lässt sich ebenso in eigene Extbase Repositories oder direkte QueryBuilder-Queries einbinden. Die Berechnung erfolgt auf Datenbankebene (MySQL/MariaDB), nicht in PHP. Das ist performancekritisch: Eine PHP-basierte Distanzberechnung über 10.000 Standorte dauert Sekunden, eine SQL-basierte Berechnung mit Index Millisekunden. Für einen Index auf den Koordinatenfeldern empfiehlt sich ein Spatial Index, sofern die Datenbank MySQL 5.7+ oder MariaDB 10.2+ verwendet.

Häufige Probleme und Lösungen

Problem: Geocoding liefert falsche Koordinaten für deutsche Adressen. Deutsche Adressen mit Umlauten (Nürnberger Straße, Lübeck) können Probleme verursachen, wenn die API die Zeichenkodierung nicht korrekt verarbeitet. Die Lösung: Sicherstellen, dass die Adressdaten in UTF-8 an die API gesendet werden. maps2 übergibt die Adresse URL-kodiert an den Dienst, aber Legacy-Datenbankfelder mit Latin1-Encoding können hier stören. Eine Datenbank-Konvertierung auf UTF-8mb4 löst das dauerhaft.

Problem: Google Geocoding API gibt “OVER_QUERY_LIMIT” zurück. Bei Batch-Geocoding mit mehr als 50 Requests pro Sekunde drosselt Google die API. Die Lösung: im Batch-Lauf unter dem Limit von 3.000 Requests pro Minute bleiben. Für große Batches den Import über Nacht laufen lassen oder in der Google Cloud Console ein höheres Kontingent beantragen.

Problem: Nominatim liefert bei gleicher Adresse unterschiedliche Ergebnisse. OpenStreetMap-Daten werden von der Community gepflegt und können sich ändern. Eine Adresse, die gestern korrekt geocodiert wurde, kann morgen leicht abweichende Koordinaten liefern, wenn jemand die OSM-Daten bearbeitet hat. Die Lösung: Einmal geocodierte Koordinaten als “verifiziert” markieren und nur bei manueller Änderung der Adresse neu geocodieren. maps2 geocodiert ohnehin nur neu, wenn sich die Adresse ändert.

Migration und Versions-Kompatibilität

Eine Extension geocoordinates ist weder im TER noch auf Packagist veröffentlicht. Geocoding bringt maps2 von Stefan Froemken (jweiland.net) selbst mit. tt_address hat mit ttaddress:geocode einen eigenen Geocoding-Befehl; beide lassen sich unabhängig voneinander einsetzen.

Für TYPO3 v13 und v14 gibt es maps2 in eigenen Versionsreihen, aktuell 12.2.0 und 13.1.0. Die Extension nutzt stabile TYPO3-APIs (DataHandler Hooks, Extbase Repositories), die sich zwischen Versionen wenig ändern.

Wer von einem manuellen Geocoding-Workflow (Google Maps aufrufen, Koordinaten kopieren, in TYPO3 eintragen) auf eine Geocoding-Extension umsteigt, kann die bestehenden Koordinaten beibehalten. Der Befehl ttaddress:geocode schreibt nur in leere Koordinatenfelder, maps2 geocodiert bei Adressänderungen neu. Bereits vorhandene Koordinaten werden nicht überschrieben, es sei denn, der Administrator löst einen manuellen Re-Geocoding-Lauf aus.

Gosign kombiniert geocoordinates standardmäßig mit maps2, um einen vollständigen Filialfinder-Stack zu liefern: Adresseingabe durch den Redakteur, automatisches Geocoding im Hintergrund, Kartenanzeige mit Marker und Popup im Frontend, Umkreissuche mit PLZ-Eingabe für den Besucher. Der Stack ist in 2 bis 3 Tagen aufgesetzt und deckt die Anforderungen von 90% aller Filialfinder-Projekte ab.