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 - Strasse, Hausnummer, PLZ, Stadt. Die Umrechnung von Adresse zu Koordinate (Geocoding) passiert nicht von allein. geocoordinates löst dieses Problem automatisiert: Die Extension ü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. geocoordinates registriert einen DataHandler-Hook auf die tt_address-Tabelle. Sobald ein Redakteur eine Adresse ändert oder einen neuen Standort anlegt, wird im Hintergrund der Geocoding-Service aufgerufen. Die Koordinaten werden in die Datenbankfelder latitude und longitude geschrieben. Die Karten-Extension maps2 liest diese Felder und platziert 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 Strasse und PLZ, aber keine Koordinaten. geocoordinates bietet einen CLI-Command, der alle Datensätze ohne Koordinaten in einem Batch-Lauf geocodiert. Bei der Google Geocoding API liegt das kostenlose Kontingent bei 40.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, geocoordinates 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

geocoordinates integriert sich als DataHandler-Hook in den TYPO3 Core. Die Extension überwacht konfigurierbare Tabellen und Felder. Wenn sich ein überwachtes Adressfeld ändert, wird asynchron ein Geocoding-Request ausgelöst.

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 40.000/Monat (mit 200 USD Guthaben). 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 werden in konfigurierbaren Datenbankfeldern gespeichert. Standard: latitude und longitude als DOUBLE-Felder. Die Extension kann über TCA-Konfiguration auf jede beliebige Tabelle angewendet werden, nicht nur auf tt_address.

Für die Umkreissuche stellt geocoordinates eine Haversine-Distanz-Funktion bereit, die in Extbase Repositories oder direkte QueryBuilder-Queries eingebunden werden kann. 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 Strasse, 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. geocoordinates kodiert standardmässig in UTF-8, 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: Rate-Limiting im Batch-Command aktivieren (max. 40 Requests/Sekunde für Standard-Accounts). Für grosse Batches den Import über Nacht laufen lassen oder auf einen Premium-Plan upgraden.

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. geocoordinates unterstützt dieses Pattern über ein zusätzliches Datenbankfeld.

Migration und Versions-Kompatibilität

geocoordinates ist als Composer-Paket für TYPO3 v10 bis v12 verfügbar. Die Extension wird von Stefan Froemken gepflegt, der auch maps2 entwickelt. Die beiden Extensions sind aufeinander abgestimmt, können aber unabhängig voneinander eingesetzt werden.

Für TYPO3 v13 ist die Kompatibilität in der Regel zeitnah nach dem LTS-Release gegeben. 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 geocoordinates umsteigt, kann die bestehenden Koordinaten beibehalten. Die Extension schreibt nur in leere Koordinatenfelder oder bei Adressänderungen. Bereits vorhandene Koordinaten werden nicht überschrieben, es sei denn, der Administrator löst einen manuellen Re-Geocoding-Lauf aus.

Gosign kombiniert geocoordinates standardmässig 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.