maps2 for TYPO3

Why maps2 has become the standard solution for maps in TYPO3

Every second corporate website needs a map display - for locations, branches, event venues or delivery areas. In TYPO3, maps2 has established itself as the most widely used maps extension because it simultaneously supports three map providers: Google Maps, OpenStreetMap and Mapbox. This gives organizations genuine choice. Those wanting to avoid Google Maps for privacy reasons can switch to OpenStreetMap without replacing the extension.

maps2 goes far beyond a simple map embed. The extension generates markers directly from TYPO3 records, supports clustering for large marker volumes and offers routing functions. For editors, creating new locations is as easy as creating a normal TYPO3 content element.

Typical use cases

Branch finders for companies with 10 to 500 locations. A retail company wants to offer an interactive branch finder on its website. Each branch is stored as a tt_address record or custom record in TYPO3. maps2 reads the addresses, geocodes them (in combination with the geocoordinates extension) and displays them as markers on the map. Clicking a marker opens a popup with address, opening hours and contact details. With more than 50 markers, maps2 activates automatic clustering to keep the map readable.

Real estate websites with property maps. Real estate websites on TYPO3 use maps2 together with the OpenImmo extension. Every imported property is automatically displayed on the map. Users can filter by region and switch between map and list views.

Event and venue pages. Cultural institutions, trade shows or municipalities display event locations on a map. maps2 can be linked with any Extbase extension that contains address data - whether cal, tt_address or custom extensions.

Technical architecture

maps2 is built as an Extbase extension and uses the TYPO3 plugin system for frontend output. The central architectural decision is the provider abstraction: the extension defines a unified interface for map rendering, implemented by three providers.

• Google Maps Provider: uses the Google Maps JavaScript API v3. Requires an API key with Maps JavaScript API and Geocoding API enabled. Cost: approx. 7 USD per 1,000 map loads after the free tier (28,000/month).
• OpenStreetMap Provider: uses Leaflet.js as the rendering library with OSM tiles. No API costs, no registration needed. Limitation: OSM tile servers have a fair-use limit. For websites with more than 50,000 page views per month, a dedicated tile server or a commercial provider like MapTiler is recommended.
• Mapbox Provider: premium option with custom map styles. Cost: 50,000 free map loads per month, then 0.50 USD per 1,000.

The extension stores map configurations (zoom, center, style) in its own database tables. Markers are created through relations to arbitrary TYPO3 records - maps2 is not limited to a specific record type. Through a TCA override, developers can link any table with map data.

Dependencies: TYPO3 Core (v11+), optionally geocoordinates for automatic geocoding of addresses. For frontend display, maps2 requires the JavaScript API of the chosen provider. For Google Maps, the API is loaded via an external script tag; for OpenStreetMap, Leaflet.js is shipped locally as a dependency.

Common problems and solutions

Map not displaying, only gray area. With Google Maps, the API key is the problem in 90% of cases. Either it is missing, billing is not activated (Google has required a stored credit card since 2018), or the allowed domains in the API key do not match the website. Solution: check in the Google Cloud Console whether Maps JavaScript API is enabled and the key is authorized for the correct domain.

Markers appear at wrong positions. The cause is frequently incorrect or missing geocoding. When addresses lack coordinates, maps2 attempts to resolve them through the configured geocoding service. With imprecise addresses (e.g. only postal code without street), markers land in the city center instead of the actual location. Solution: correct coordinates through a one-time batch geocoding run and store them as fixed values in the record.

Performance issues with more than 200 markers. The JavaScript library renders each marker individually into the DOM. From 200 markers onward, this becomes noticeably slow on mobile devices. Solution: activate marker clustering and if necessary implement server-side filtering so only markers in the current map viewport are loaded.

Migration and version compatibility

maps2 is actively maintained by Stefan Froemken and is available for TYPO3 v11 and v12 LTS. Compatibility with TYPO3 v13 is typically established shortly after the LTS release. The extension has a stable API and minimal breaking changes between major versions.

For those migrating from an older maps extension (e.g. wec_map, od_googlemaps or ke_daysspecial_map), the database structure must be adjusted. maps2 uses its own tables for map configuration that are not compatible with older extensions. A migration typically involves: coordinate export from the old extension, creating new maps2 records, linking with existing TYPO3 records.

When switching from Google Maps to OpenStreetMap (frequently for GDPR (UK: UK GDPR) reasons), only the provider configuration in maps2 needs to be changed. Templates and marker data remain identical. Gosign has completed this switch for multiple clients in under one day. The GDPR motivation: Google Maps transfers personal data (IP address, browser fingerprint) to Google servers in the US. With OpenStreetMap, data stays in Europe and a consent banner for map services becomes unnecessary. For companies that embed maps on every page, this also improves user experience because the map is immediately visible without the visitor first consenting via the cookie banner.