Geocoding for TYPO3

Why every TYPO3 branch finder fails on data quality without geocoding

Branch finders, dealer locators and radius searches all share the same foundation: GPS coordinates. But companies store location data as addresses - street, house number, postal code, city. The conversion from address to coordinates (geocoding) does not happen by itself. geocoordinates solves this problem automatically: the extension monitors address fields in TYPO3 records and calculates the corresponding GPS coordinates via a geocoding service whenever a change is made.

Without a geocoding extension, editors would have to manually copy latitude and longitude from Google Maps for every location. For 50 locations, that is an hour of work. For 500 locations, a full working day - and the process starts over with every address change.

Typical use cases

Automatic geocoding for tt_address records. A company with 120 locations in Germany, Austria and Switzerland maintains all addresses in the TYPO3 extension tt_address. geocoordinates registers a DataHandler hook on the tt_address table. Whenever an editor changes an address or creates a new location, the geocoding service is called in the background. The coordinates are written to the latitude and longitude database fields. The maps extension maps2 reads these fields and places the marker in the correct position.

Batch geocoding during data migrations. A company migrates 2,000 addresses from a legacy system to TYPO3. The imported records have street and postal code but no coordinates. geocoordinates offers a CLI command that geocodes all records without coordinates in a batch run. With the Google Geocoding API, the free tier includes 40,000 requests per month - more than sufficient for a one-time migration.

Radius search based on postal codes. A trades business offers radius search: “Find the nearest partner in your area.” The visitor enters their postal code, geocoordinates converts the postal code into coordinates, and a SQL distance calculation (Haversine formula) returns all locations within a 25, 50 or 100 km radius, sorted by distance.

Technical architecture

geocoordinates integrates as a DataHandler hook into the TYPO3 Core. The extension monitors configurable tables and fields. When a monitored address field changes, a geocoding request is triggered asynchronously.

The extension supports two geocoding providers:

• Google Geocoding API: high accuracy, globally available, requires an API key with billing enabled. Cost: 5 USD per 1,000 requests, free up to 40,000/month (with 200 USD credit). Advantage: intelligently processes incomplete or incorrect addresses.
• OpenStreetMap Nominatim: free, no registration required. Limitations: maximum query rate of 1 request/second, terms of use require a custom user agent. Accuracy in rural areas is sometimes lower than Google.

Coordinates are stored in configurable database fields. Default: latitude and longitude as DOUBLE fields. The extension can be applied to any table via TCA configuration, not just tt_address.

For radius search, geocoordinates provides a Haversine distance function that can be integrated into Extbase repositories or direct QueryBuilder queries. The calculation runs at the database level (MySQL/MariaDB), not in PHP. This is performance-critical: a PHP-based distance calculation over 10,000 locations takes seconds, a SQL-based calculation with an index takes milliseconds. For an index on coordinate fields, a spatial index is recommended if the database uses MySQL 5.7+ or MariaDB 10.2+.

Common problems and solutions

Geocoding returns incorrect coordinates for addresses. Addresses with special characters (e.g. German umlauts in street names) can cause issues if the API does not process the character encoding correctly. Solution: ensure address data is sent to the API in UTF-8. geocoordinates encodes in UTF-8 by default, but legacy database fields with Latin1 encoding can interfere. A database conversion to UTF-8mb4 solves this permanently.

Google Geocoding API returns “OVER_QUERY_LIMIT”. During batch geocoding with more than 50 requests per second, Google throttles the API. Solution: activate rate limiting in the batch command (max. 40 requests/second for standard accounts). For large batches, run the import overnight or upgrade to a premium plan.

Nominatim returns different results for the same address. OpenStreetMap data is community-maintained and can change. An address that was correctly geocoded yesterday may return slightly different coordinates tomorrow if someone edited the OSM data. Solution: mark geocoded coordinates as “verified” and only re-geocode on manual address changes. geocoordinates supports this pattern through an additional database field.

Migration and version compatibility

geocoordinates is available as a Composer package for TYPO3 v10 through v12. The extension is maintained by Stefan Froemken, who also develops maps2. The two extensions are coordinated but can be used independently.

For TYPO3 v13, compatibility is typically established shortly after the LTS release. The extension uses stable TYPO3 APIs (DataHandler hooks, Extbase repositories) that change little between versions.

Those switching from a manual geocoding workflow (open Google Maps, copy coordinates, enter in TYPO3) to geocoordinates can keep existing coordinates. The extension only writes to empty coordinate fields or on address changes. Existing coordinates are not overwritten unless the administrator triggers a manual re-geocoding run.

Gosign combines geocoordinates with maps2 by default to deliver a complete branch finder stack: address entry by the editor, automatic geocoding in the background, map display with markers and popups in the frontend, radius search with postal code input for the visitor. The stack is set up in 2 to 3 days and covers the requirements of 90% of all branch finder projects.