maps2 for TYPO3

Why maps2 is one of the standard solutions 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 one of the most used maps extensions because it simultaneously supports two map providers: Google Maps and OpenStreetMap. 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 with Google Maps and draws routes, areas and radii. 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 (through the Google or OpenStreetMap geocoding service built into maps2) and displays them as markers on the map. Clicking a marker opens a popup with address, opening hours and contact details. For many markers, clustering can be switched on for Google Maps 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 two 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 (10,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.
• Tile server: the map tile URL is freely configurable, so your own server or a commercial provider can replace the OSM servers.

The extension stores points, routes, areas and radii in its own database table, zoom and map size in the plugin settings. 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+), maps2 brings its own 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 has its own series for each LTS version: 10.x for v11, 11.x for v12, 12.x for v13 and 13.x for v14. Major versions do bring changes, such as the switch from plugins to content elements in 12.0.0; the documentation describes each step including the upgrade wizard.

For those migrating from an older maps extension (e.g. wec_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 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 such as the IP address to Google, including servers outside the EU. With OpenStreetMap tiles from your own tile server, the data goes to no one else, 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.