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. A geocoding extension such as maps2 solves this problem automatically: it 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. maps2 connects the tt_address table through its registry and reacts to every save via a DataHandler hook. Whenever an editor changes an address or creates a new location, the geocoding service is called in the background. maps2 stores the coordinates in its own location record linked to the address and uses it to place 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. tt_address ships the CLI command ttaddress:geocode, which geocodes all records without coordinates in a batch run via the Google Geocoding API. With the Google Geocoding API, the free tier includes 10,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, a geocoding service 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

maps2 integrates as a DataHandler hook into the TYPO3 Core. The extension monitors the tables and address fields connected to its registry via TCA. When a monitored address field changes, maps2 triggers a geocoding request while saving.

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 10,000/month (since March 2025, replacing the former 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.

maps2 stores the coordinates in its own location record in the fields latitude and longitude, tt_address in decimal fields of the same name. The extension can be applied to any table via TCA configuration, not just tt_address.

For radius search, maps2 calculates the distance with an SQL formula in the QueryBuilder; a Haversine function can likewise be integrated into your own 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. maps2 passes the address URL-encoded to the service, 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: stay below the limit of 3,000 requests per minute in the batch run. For large batches, run the import overnight or request a higher quota in the Google Cloud Console.

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. maps2 only re-geocodes anyway when the address changes.

Migration and version compatibility

An extension called geocoordinates is published neither in the TER nor on Packagist. maps2 by Stefan Froemken (jweiland.net) brings geocoding itself. tt_address has its own geocoding command, ttaddress:geocode; both can be used independently.

For TYPO3 v13 and v14, maps2 has its own version series, currently 12.2.0 and 13.1.0. 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 a geocoding extension can keep existing coordinates. The ttaddress:geocode command only writes to empty coordinate fields, and maps2 re-geocodes 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.