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)

25Credits

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.

StylePurpose
standard-hellStandard map, light. The default.
standard-dunkelStandard map, dark, for example for a dark theme in your application.
weissLight greys only. A base for heatmaps and data layers that bring their own colour.
schwarzDark 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.

SwitchEffect
langLabel 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.
poistrue (default) shows places as a symbol in the colour of their category, false hides them.
labelstrue (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.

GET/v1/metron/style

Returns 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

  • keystring
    Preferred

    Public key (pk_). Alternatively a key in the Authorization header; sk_ keys only there.

  • stylestringOptionalDefault: standard-hell

    standard-hell, standard-dunkel, weiss or schwarz.

  • langstringOptionalDefault: de

    Label language at start, for example de or en. A language the style does not offer has no effect.

  • worldviewstringOptionalDefault: neutral

    Country 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.

  • sessionstringOptional

    ID 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": [ ... ]
}
POST/v1/metron/session/refresh

Renews 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

  • keystring
    Preferred

    Public key (pk_). Alternatively a key in the Authorization header; sk_ keys only there.

  • sessionstring (body)Optional

    ID 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_request 400: an sk_ key in the key parameter.
  • invalid_api_key 401: the key is missing or invalid.
  • insufficient_credits 402: 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_denied 403: 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_denied 403: the key may not use metron:maps. For IP ranges the code is key_ip_denied.
  • model_not_found 404: unknown style name. If METRON Maps is not enabled for the account, the API answers 404 as well.
  • rate_limit_exceeded 429: the account's rate limit is exceeded. Style requests and renewals count, tiles do not.
  • service_unavailable 503: 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.