Base maps
METRON Maps
Your own base map for your application, in four styles, with labels in many languages.
Pricing
Map load (up to 4 hours and 3,000 tiles)
What METRON Maps is for
METRON Maps provides the base map on which your application shows its own content: locations, routes, heatmaps or measurements. The map comes from one source together with METRON Places and METRON Routes: places on the map lead straight to the place lookup with one click, and routes fit the streets exactly. Billing is per map load, not per tile.
Styles
All styles use the same tiles. Switching the style in the same map costs nothing.
| Style | Purpose |
|---|---|
| standard-hell | Standard map, light. The default. |
| standard-dunkel | Standard map, dark, for example for a dark theme in your application. |
| weiss | Light greys only. A base for heatmaps and data layers that bring their own colour. |
| schwarz | Dark greys only, likewise a base for coloured data layers. |
Keys and allowed sites
In the browser, use a public key (pk_). Pass it as the key parameter, since MapLibre loads without custom headers. Access is enabled per account (scope metron:maps). You create public keys with their allowed sites yourself in the dashboard under API keys.
A pk_ key only works on its allowed sites. What counts is the Origin header, otherwise the origin of the Referer; the browser sets both itself. An allowed site is scheme, host and port if any, in lower case and without a path, such as https://www.example.com. An entry https://*.example.com covers all subdomains at any depth, but not example.com itself. Requests without Origin and Referer, for example from a sandboxed frame or from file://, are refused with 403 (key_origin_denied).
Outside a browser, Origin and Referer can be forged. That is why a public key opens nothing but METRON. Give every pk_ key a monthly budget as well, limit it to the scopes it needs (for example metron:maps only) and, where the callers are known, to IP ranges.
On the server you can send any key in the Authorization header. An sk_ key in the key parameter is refused with 400, because URLs end up in logs and histories.
Embedding the map
You need MapLibre GL JS 5.6 or later and the metron.mjs client. The client fetches the style with your pk_ key, keeps the tile token fresh and moves to a new session when needed, without the map noticing.
index.html
<!doctype html>
<html lang="de">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<style>html, body, #map { height: 100%; margin: 0; }</style>
</head>
<body>
<div id="map"></div>
<script type="module" src="./main.js"></script>
</body>
</html>main.js
import * as maplibregl from "maplibre-gl"; // version 5.6 or later
import "maplibre-gl/dist/maplibre-gl.css";
import { metron, MetronAttribution } from "./metron.mjs";
// One helper per map: each map is one session (one map load).
const maps = metron({ key: "pk_your_public_key", endpoint: "https://api.centra.dbpg.io", maplibregl });
const map = new maplibregl.Map({
container: "map",
style: await maps.style("standard-hell", { lang: "de" }),
center: [11.5755, 48.1372],
zoom: 13,
attributionControl: false, // replaced by MetronAttribution
});
map.addControl(new MetronAttribution()); // required: names the data sources
// Another style in the same session, not billed again:
// map.setStyle(await maps.style("standard-dunkel"));
// When the map goes away:
// map.remove(); maps.close();metron({ key, endpoint, maplibregl }) creates a client for exactly one map; endpoint defaults to https://api.centra.dbpg.io. maps.style(name, { lang, worldview }) returns the finished style. The client loads tiles through its own MapLibre protocol: if a token is refused, for example after the computer was asleep, it renews it and fetches the tile a second time before MapLibre sees an error. The onSession({ session, billed }) option tells you when a new session begins. Call maps.close() when you remove the map.
Sessions and billing
Billing is per map load. One map load is one session.
- A session costs 25 credits and covers up to 4 hours and up to 3,000 tiles, whichever comes first.
- It begins with the first style request without a running session. Every new map is a new session, also after reloading the page. An unknown or expired session ID, or one that belongs to another account, opens a new session as well.
- Switching the style in the same map and renewing the tile token cost nothing. The token is valid for 15 minutes; the client renews it after two thirds of that time.
- After 4 hours, the next renewal begins a new, billed session. At 3,000 tiles the client renews on its own, and a new, billed session begins then too. The map keeps running without interruption.
- Every tile counts, including tiles served from cache.
- Callers that do not renew, such as a script without the client, receive only status 401 from 3,500 tiles in a session.
Only the start of a session is billed. Error responses cost nothing, and neither does an unknown style name. The billed field of a renewal shows whether it billed a new session.
Language, places and labels
These switches are style settings (global-state). They take effect at once, without new tiles and without a new session. You can already set the language when requesting the style, with lang.
| Switch | Effect |
|---|---|
| lang | Label language, default de. Possible values are the languages the style lists under metadata["dbpg:languages"]. Where a translation is missing, the local name is shown. |
| pois | true (default) shows places as a symbol in the colour of their category, false hides them. |
| labels | true (default) shows all labels, symbols and road shields, false hides them. What remains is the plain base map. |
map.setGlobalStateProperty("lang", "en"); // labels in English, no new tiles
map.setGlobalStateProperty("pois", false); // hide the place symbols
map.setGlobalStateProperty("labels", false); // plain base map without any labels
// After map.setStyle(...) the style starts with its defaults again:
map.on("style.load", () => map.setGlobalStateProperty("lang", "en"));Custom markers with the place symbols
The place symbols are in the style's poi sprite: a shape with softly rounded corners in the category colour, with a white symbol inside. Use them for your own markers with the name poi:<symbol>-<colour>, for example poi:cafe-c2410c. The colours differ per style; map.listImages() shows which names the loaded style contains.
map.on("load", () => {
map.addSource("shops", {
type: "geojson",
data: { type: "FeatureCollection", features: [
{ type: "Feature", geometry: { type: "Point", coordinates: [11.5755, 48.1372] }, properties: {} },
] },
});
map.addLayer({
id: "shops",
type: "symbol",
source: "shops",
layout: { "icon-image": "poi:cafe-c2410c", "icon-allow-overlap": true },
});
});
// Symbol names in the loaded style:
console.log(map.listImages().filter((id) => id.startsWith("poi:")));Linking places to METRON Places
Places on the map carry the same ID as in METRON Places, as a number: type times 2^44 plus OSM ID (type 1 node, 2 way, 3 relation). Feature ID 17592186167872 (2^44 + 123456) is therefore the place osm:n123456. The METRON Places lookup accepts both forms, so a click on the map leads straight to address, opening hours and further details. The lookup is billed at METRON Places prices. Details are in METRON Places.
// Feature id = type * 2^44 + OSM id (type 1 node, 2 way, 3 relation)
const LETTER = { 1: "n", 2: "w", 3: "r" };
const placeId = (featureId) => {
const type = Math.floor(featureId / 2 ** 44);
return LETTER[type] ? `osm:${LETTER[type]}${featureId % 2 ** 44}` : null;
};
map.on("click", "pois", async (e) => {
const featureId = e.features[0].id; // e.g. 17592186167872 = osm:n123456
console.log(placeId(featureId));
const res = await fetch(`https://api.centra.dbpg.io/v1/metron/places/${featureId}?key=pk_your_public_key`);
if (res.ok) {
const { feature, details } = await res.json();
}
});Endpoints
The client calls both endpoints itself. You only need them when working without the client.
/v1/metron/styleReturns a finished MapLibre style with signed tile URLs for one session. Without a running session a new, billed session begins; with the ID of a running session of the same account (style switch) it does not. The session data is under metadata. An unknown style gives 404 and costs nothing. The response is meant for this map only and is not cached (Cache-Control: private, no-store).
Parameter
keystringPreferredPublic key (pk_). Alternatively a key in the Authorization header; sk_ keys only there.
stylestringOptionalDefault:standard-hellstandard-hell, standard-dunkel, weiss or schwarz.
langstringOptionalDefault:deLabel language at start, for example de or en. A language the style does not offer has no effect.
worldviewstringOptionalDefault:neutralCountry view for borders and disputed names, as an ISO country code such as in; default neutral. A view the style does not offer has no effect.
sessionstringOptionalID of the running session (sess_…), to switch the style in the same map.
Request
curl "https://api.centra.dbpg.io/v1/metron/style?key=pk_your_public_key&style=standard-hell&lang=de" \
-H "Origin: https://www.example.com"Response
{
"version": 8,
"name": "...",
"sources": {
"dbpg": { "type": "vector", "tiles": ["https://.../tiles/dbpg/{z}/{x}/{y}.mvt?t=..."], ... },
...
},
"state": { "lang": { "default": "de" }, "pois": { "default": true }, "labels": { "default": true }, ... },
"metadata": {
"dbpg:session": "sess_...",
"dbpg:token-ttl": 900,
"dbpg:tile-limit": 3000,
"dbpg:attribution": [ ... ]
},
"layers": [ ... ]
}/v1/metron/session/refreshRenews the tile token of a session. While the session is running the renewal is free and billed is false. If it is over (4 hours or 3,000 tiles), missing or belongs to another account, a new, billed session with a new ID begins; billed is then true. ttl is the token lifetime in seconds, tileLimit the number of tiles per session.
Parameter
keystringPreferredPublic key (pk_). Alternatively a key in the Authorization header; sk_ keys only there.
sessionstring (body)OptionalID of the session whose token is renewed, in the JSON body.
Request
curl -X POST "https://api.centra.dbpg.io/v1/metron/session/refresh?key=pk_your_public_key" \
-H "Origin: https://www.example.com" \
-H "Content-Type: application/json" \
-d '{ "session": "sess_..." }'Response
{
"session": "sess_...",
"token": "...",
"ttl": 900,
"tileLimit": 3000,
"billed": false
}Attribution
Every map must name its sources visibly. Create the map with attributionControl: false and add MetronAttribution from the client. The control shows one line at the bottom right with “dbpg METRON Maps”, the source notices from the style (metadata["dbpg:attribution"]) and a link to the licence page:
- © OpenStreetMap, linking to openstreetmap.org/copyright. This notice stays visible on narrow maps (below 480 pixels wide) too.
- © ESA WorldCover
- © Copernicus DEM
- Lizenzen (licences): the licence page with all sources and the full texts. On narrow maps the two notices above appear only there.
If you use a control of your own, show the same notices, at least “© OpenStreetMap” without a further click. The map data is licensed under the Open Database License (ODbL).
Errors
Errors are returned as JSON with an error field. They cost nothing.
bad_request400: an sk_ key in the key parameter.invalid_api_key401: the key is missing or invalid.insufficient_credits402: the balance does not cover a new session. If the key's monthly budget is used up, the code is key_budget_exhausted.key_origin_denied403: the site is not allowed for this pk_ key, or the request names no site. The message names the site it saw, so you can add it.key_scope_denied403: the key may not use metron:maps. For IP ranges the code is key_ip_denied.model_not_found404: unknown style name. If METRON Maps is not enabled for the account, the API answers 404 as well.rate_limit_exceeded429: the account's rate limit is exceeded. Style requests and renewals count, tiles do not.service_unavailable503: the service is temporarily unavailable.- Tiles: an expired token or an exhausted session gives 401 on a tile request. The client then renews on its own; without the client, call /v1/metron/session/refresh.