tile_proxy
main
en
codemacher UG
This document is published under the Creative Commons BY 4.0 license.
Mon, 08 Dec 2025 15:08:44 +0000
This documentation is for the TYPO3 extension tile_proxy.
Table of Contents:
With Tile Proxy you can integrate OpenStreetMap maps GDPR in a compliant way without any third party requests from the client. For a given area, the data is loaded from OpenStreetMap and cached, therefore you do not need a cookie banner or blocker to use OpenStreetMap cookie banner or blocker to use OpenStreetMap. A proxy is also provided for geocoding nominatim.
Tip
Content blocker are also not desired:
https://edpb.europa.eu/sites/default/files/files/file1/edpb_guidelines_202005_consent_en.pdf
(Paragraph 40, example 6a)
You can install tile proxy with the following shell command:
composer req codemacher/tile_proxyIf you want to install tile proxy traditionally with ExtensionManager, follow these steps:
Get Extensionstile proxyIt is necessary to include at least the basic TypoScript provided by this extension.
Go module Web > Template and chose your root page. It should already contain a TypoScript template record. Switch to view Info/Modify and click on Edit the whole template record.
Switch to tab Includes and add the following templates from the list to the right: Tile Proxy (tile_proxy).
Create a page with the type (doktype) "Tile Proxy Endpoint" for a tile proxy or "Nominatim Proxy Endpoint" for a geocoding proxy. The easiest way is to drag a new page of this type from the toolbar and place it in a system folder.
Give the page a name and a slug. That page defines the endpoint from which the data can be retrieved.
In the settings of the endpoint page you should make the following settings:
Define a maximum range for which the data is to be loaded and made available. The bounding box can be determined by the rectangle on the map. The bounding box rectangle (green) may differ from the moving rectangle because the values are rounded.
Attention
Depending on the size of the area, storage space is required accordingly. All images for the maps that lie within the bounding box are stored on the server. This can quickly become several GB in size, so the area should be chosen as small as possible. This extension is probably not suitable for the entire world, rather for a small section.
Tip
In your a JavaScript implementation for the frontend, the map section should be restricted analogously. If your map uses different aspect ratios depending on the resolution, the deliverable area should be chosen larger than defined in the JavaScript. With Leaflet, for example, it can happen that an area larger the maxBounds is still displayed.
If this option is set, all tiles outside the bounding box are passed through directly. If this option is switched off, no queries outside the bounding box will be forwarded.
All tiles with a zoom level >= this will cached. A zoom level 6 requires about 20MB, but beware, the required size increases exponentially.
All tiles with a zoom level > this will not cached.
Each tile is stored as an image on your server. This time indicates on the one hand how long this image is not updated again by a request to OpenStreetMap, on the other hand this time is sent as caching time to the client for each tile.
If an external domain requests the proxy, you can define a list of allowed referrer domains here. In case this is not configured the settings from the extension configuration are used.
In the settings of the endpoint page you should make the following settings:
Each request to nominatim is stored in the database. This time in seconds determines how long the entry is valid and remains stored.
If an external domain requests the proxy, you can define a list of allowed referrer domains here. In case this is not configured the settings from the extension configuration are used.
The following settings can be made under the extension settings:
If this option is activated, all cached tiles are deleted when the TYPO3 cache is cleared.
If this option is activated, all cached requests are deleted when the TYPO3 cache is cleared.
The maximum number of records stored in the database.
This is the maximum size of the file cache used for tiles over all endpoints (if more than one endpoint is specified)
If there is an error when loading a tile, a standard error image is delivered. Here you can define a path to an alternative error image.
If an image outside the defined bounding box is requested, a standard image is returned. Here you can define a path to an alternative image.
If an external domain request the proxy, you can define a list of globally allowed referrer domains here. It's helpful for headless TYPO3 installations, where the frontend and backend are on different domains and you want to configure it by environment variables. This config is a fallback for the allowed referrer domains configured in the page settings of the endpoint. If domains in the config of the page settings, this config won't be used.
With this extension you can define a page in the TYPO3 backend as an endpoint for maps.
If the slug for your page is e.g. tile-proxy, the data can be retrieved from:
/tile-proxy/?provider=osm&z={z}&x={x}&y={y}&s={s}provider
Currently only osm (OpenStreetMap) is supported, so the value must be osm.
z
zoom level (https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames)
x
x-tile coordinate (https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames)
y
y-tile coordinate (https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames)
s
OSM subdomain for CDN
If the tile must be loaded and is not cached, this request will be mapped to:
https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.pngThe http referrer must be your own domain, localhost or configured in page settings or extension configuration, otherwise you will receive error 1001.
// Initialize the base layer
L.tileLayer('/tile-proxy/?provider=osm&z={z}&x={x}&y={y}&s={s}', {
attribution: '© <a href="https://www.openstreetmap.org/copyright" target="_blank">OpenStreetMap</a> contributors',
}).addTo(map);var osmSource = new ol.source.XYZ({
attributions : '© <a href="https://www.openstreetmap.org/copyright" target="_blank">OpenStreetMap</a> contributors',
urls: [
'/tile-proxy/?provider=osm&z={z}&x={x}&y={y}&s=a',
'/tile-proxy/?provider=osm&z={z}&x={x}&y={y}&s=b',
'/tile-proxy/?provider=osm&z={z}&x={x}&y={y}&s=c',
]
});With this extension you can define a page in the TYPO3 backend as an endpoint for geocoding request to nominatim.
If the slug for your page is e.g. geo-proxy, the data can be retrieved from:
/geo-proxy/?provider=osm&apitype=search&q=06120&format=json&addressdetails=1provider
Currently only osm (OpenStreetMap) is supported, so the value must be osm.
apitype
Type of the api endpoint. Permissible types are: 'search','reverse','lookup' see https://nominatim.org/release-docs/latest/api/Overview/
all other paramers
all other parameters are forwarded directly to the nominatim-api.
If the request must be loaded and is not cached, this request will be mapped to:
https://nominatim.openstreetmap.org/search?q=06120&format=json&addressdetails=1The http referrer must be your own domain, localhost or configured in page settings or extension configuration, otherwise you will receive error 1001.
Here are simples example for Leaflet and OpenLayers. To try it out, simply save the file in the typo3 webroot and open it in the browser. (The endpoint "/tile-proxy" must of course be defined).
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Quick Start - OpenLayer</title>
<script src="https://cdn.jsdelivr.net/npm/ol@v7.2.2/dist/ol.js"></script>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/ol@v7.2.2/ol.css">
<style>
html,
body {
height: 100%;
margin: 0;
}
</style>
</head>
<body>
<div id="map" style="width: 600px; height: 400px;"></div>
<script>
let osmSource = new ol.source.XYZ({
attributions: '© ' +
'<a href="https://www.openstreetmap.org/copyright" target="_blank">OpenStreetMap</a> ' +
'contributors.',
crossOrigin: 'anonymous',
urls: [
'/tile-proxy/?provider=osm&z={z}&x={x}&y={y}&s=a',
'/tile-proxy/?provider=osm&z={z}&x={x}&y={y}&s=b',
'/tile-proxy/?provider=osm&z={z}&x={x}&y={y}&s=c',
]
});
let extent = ol.proj.transformExtent([11.86, 51.41, 12.07, 51.55], 'EPSG:4326', 'EPSG:3857')
let center = ol.proj.fromLonLat([11.940057754516602, 51.4974250793457]);
var map = new ol.Map({
layers: [
new ol.layer.Tile({
source: osmSource
})
],
target: 'map',
view: new ol.View({
center: center,
zoom: 12,
minZoom: 14
})
});
</script>
</body>
</html><!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Quick Start - Leaflet</title>
<link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.3/dist/leaflet.css"
integrity="sha256-kLaT2GOSpHechhsozzB+flnD+zUyjE2LlfWPgU04xyI=" crossorigin="" />
<script src="https://unpkg.com/leaflet@1.9.3/dist/leaflet.js"
integrity="sha256-WBkoXOwTeyKclOHuWtc+i2uENFpDZ9YPdf5Hf+D7ewM=" crossorigin=""></script>
<style>
html,
body {
height: 100%;
margin: 0;
}
</style>
</head>
<body>
<div id="map" style="width: 600px; height: 400px;"></div>
<script>
let markerLocation = [51.4974250793457, 11.940057754516602];
const map = L.map('map').setView(markerLocation, 13);
let southWest = L.latLng(51.41, 11.86),
northEast = L.latLng(51.55, 12.07),
bounds = L.latLngBounds(southWest, northEast);
map.setMaxBounds(bounds);
const tiles = L.tileLayer('/tile-proxy/?provider=osm&z={z}&x={x}&y={y}&s={s}', {
minZoom: 13,
attribution: '© <a href="http://www.openstreetmap.org/copyright">OpenStreetMap</a>'
}).addTo(map);
const marker = L.marker(markerLocation).addTo(map)
.bindPopup('<b>Hello world!</b><br />I am a popup.').openPopup();
</script>
</body>
</html>