Basiskarten

METRON Maps

Eine eigene Basiskarte für Ihre Anwendung, in vier Stilen, mit Beschriftung in vielen Sprachen.

Preise

Kartenaufruf (bis 4 Std. und 3.000 Kacheln)

25Credits

Wofür METRON Maps da ist

METRON Maps liefert die Grundkarte, auf der Ihre Anwendung ihre eigenen Inhalte zeigt: Standorte, Routen, Heatmaps oder Messwerte. Die Karte kommt aus einer Hand mit METRON Places und METRON Routes: Orte auf der Karte führen per Klick direkt zum Ortsabruf, Routen liegen passgenau auf den Straßen. Abgerechnet wird je Kartenaufruf, nicht je Kachel.

Stile

Alle Stile beruhen auf denselben Kacheln. Ein Wechsel des Stils in derselben Karte kostet nichts.

StilZweck
standard-hellStandardkarte, hell. Voreinstellung.
standard-dunkelStandardkarte, dunkel, etwa für ein dunkles Erscheinungsbild Ihrer Anwendung.
weissNur helle Grautöne. Grund für Heatmaps und Datenebenen, die selbst Farbe tragen.
schwarzNur dunkle Grautöne, ebenso als Grund für farbige Datenebenen.

Schlüssel und erlaubte Seiten

Im Browser verwenden Sie einen öffentlichen Schlüssel (pk_). Er wird als Parameter key übergeben, denn MapLibre lädt ohne eigene Header. Der Zugriff ist je Konto freigeschaltet (Scope metron:maps). Öffentliche Schlüssel mit ihren erlaubten Seiten legen Sie selbst im Dashboard unter API-Schlüssel an.

Ein pk_-Schlüssel gilt nur auf seinen erlaubten Seiten. Maßgeblich ist der Header Origin, sonst der Ursprung des Referer; beide setzt der Browser selbst. Eine erlaubte Seite besteht aus Schema, Host und gegebenenfalls Port in Kleinbuchstaben, ohne Pfad, etwa https://www.example.com. Ein Eintrag https://*.example.com gilt für alle Subdomains in beliebiger Tiefe, nicht für example.com selbst. Anfragen ohne Origin und Referer, etwa aus einem Sandbox-Frame oder von file://, weist die Schnittstelle mit 403 ab (key_origin_denied).

Außerhalb eines Browsers lassen sich Origin und Referer fälschen. Ein öffentlicher Schlüssel öffnet deshalb nur METRON. Geben Sie jedem pk_-Schlüssel zusätzlich ein Monatsbudget, beschränken Sie ihn auf die Scopes, die er braucht (etwa nur metron:maps), und, wo die Aufrufer bekannt sind, auf IP-Bereiche.

Serverseitig können Sie jeden Schlüssel im Authorization-Header senden. Einen sk_-Schlüssel im Parameter key weist die Schnittstelle mit 400 ab, denn Adressen landen in Protokollen und Verläufen.

Karte einbetten

Sie brauchen MapLibre GL JS ab Version 5.6 und den Client metron.mjs. Der Client holt den Stil mit Ihrem pk_-Schlüssel, hält das Kachel-Token frisch und wechselt bei Bedarf in eine neue Sitzung, ohne dass die Karte es merkt.

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 }) erzeugt einen Client für genau eine Karte; endpoint ist mit https://api.centra.dbpg.io vorbelegt. maps.style(name, { lang, worldview }) liefert den fertigen Stil. Kacheln lädt der Client über ein eigenes MapLibre-Protokoll: Wird ein Token abgewiesen, etwa nach dem Ruhezustand des Rechners, erneuert er es und holt die Kachel ein zweites Mal, bevor MapLibre einen Fehler sieht. Mit der Option onSession({ session, billed }) erfahren Sie, wann eine neue Sitzung beginnt. Rufen Sie maps.close() auf, wenn Sie die Karte entfernen.

Sitzungen und Abrechnung

Abgerechnet wird je Kartenaufruf. Ein Kartenaufruf ist eine Sitzung.

  • Eine Sitzung kostet 25 Credits und umfasst bis zu 4 Stunden und bis zu 3.000 Kacheln, je nachdem, was zuerst erreicht ist.
  • Sie beginnt mit dem ersten Stilabruf ohne laufende Sitzung. Jede neue Karte ist eine neue Sitzung, auch nach dem Neuladen der Seite. Eine unbekannte, abgelaufene oder zu einem anderen Konto gehörende Sitzungskennung eröffnet ebenfalls eine neue Sitzung.
  • Ein Stilwechsel in derselben Karte und die Erneuerung des Kachel-Tokens kosten nichts. Das Token gilt 15 Minuten; der Client erneuert es nach zwei Dritteln dieser Zeit.
  • Nach 4 Stunden beginnt mit der nächsten Erneuerung eine neue, berechnete Sitzung. Bei 3.000 Kacheln erneuert der Client von sich aus, und auch dann beginnt eine neue, berechnete Sitzung. Die Karte läuft dabei ohne Unterbrechung weiter.
  • Jede Kachel zählt, auch eine aus dem Zwischenspeicher.
  • Wer nicht erneuert, etwa ein Skript ohne den Client, erhält ab 3.500 Kacheln einer Sitzung nur noch Status 401.

Berechnet wird nur der Beginn einer Sitzung. Fehlerantworten kosten nichts, ein unbekannter Stilname ebenfalls nicht. Ob eine Erneuerung eine neue Sitzung berechnet hat, zeigt ihr Feld billed.

Sprache, Orte und Beschriftungen

Diese Schalter sind Einstellungen des Stils (global-state). Sie wirken sofort, ohne neue Kacheln und ohne neue Sitzung. Die Sprache können Sie schon beim Stilabruf mit lang setzen.

SchalterWirkung
langSprache der Beschriftung, Voreinstellung de. Möglich sind die Sprachen, die der Stil unter metadata["dbpg:languages"] nennt. Fehlt eine Übersetzung, erscheint der Name vor Ort.
poistrue (Voreinstellung) zeigt Orte als Symbol in der Farbe ihrer Kategorie, false blendet sie aus.
labelstrue (Voreinstellung) zeigt alle Beschriftungen, Symbole und Straßenschilder, false blendet sie aus. Übrig bleibt die reine Grundkarte.
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"));

Eigene Marker mit den Ortssymbolen

Die Ortssymbole liegen im Symbolsatz poi des Stils: eine Fläche mit weich gerundeten Ecken in der Farbe der Kategorie, darin ein weißes Symbol. Für eigene Marker verwenden Sie sie mit dem Namen poi:<symbol>-<farbe>, etwa poi:cafe-c2410c. Die Farben unterscheiden sich je Stil; welche Namen der geladene Stil enthält, zeigt map.listImages().

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:")));

Orte mit METRON Places verknüpfen

Orte auf der Karte tragen dieselbe ID wie in METRON Places, als Zahl: Typ mal 2^44 plus OSM-ID (Typ 1 Knoten, 2 Weg, 3 Relation). Die Feature-ID 17592186167872 (2^44 + 123456) ist also der Ort osm:n123456. Der Ortsabruf von METRON Places nimmt beide Schreibweisen an; ein Klick auf die Karte führt damit direkt zu Adresse, Öffnungszeiten und weiteren Angaben. Der Ortsabruf wird nach den Preisen von METRON Places berechnet. Einzelheiten finden Sie bei 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();
  }
});

Endpunkte

Der Client ruft beide Endpunkte selbst auf. Sie brauchen sie nur, wenn Sie ohne den Client arbeiten.

GET/v1/metron/style

Liefert einen fertigen MapLibre-Stil mit signierten Kachel-Adressen für eine Sitzung. Ohne laufende session beginnt eine neue, berechnete Sitzung; mit der Kennung einer laufenden Sitzung desselben Kontos (Stilwechsel) nicht. Die Sitzungsangaben stehen unter metadata. Ein unbekannter Stil ergibt 404 und kostet nichts. Die Antwort ist nur für diese Karte bestimmt und wird nicht zwischengespeichert (Cache-Control: private, no-store).

Parameter

  • keystring
    Empfohlen

    Öffentlicher Schlüssel (pk_). Alternativ ein Schlüssel im Authorization-Header; sk_-Schlüssel nur dort.

  • stylestringOptionalStandard: standard-hell

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

  • langstringOptionalStandard: de

    Sprache der Beschriftung beim Start, zum Beispiel de oder en. Eine Sprache, die der Stil nicht anbietet, bleibt ohne Wirkung.

  • worldviewstringOptionalStandard: neutral

    Länderansicht für Grenzen und strittige Namen, als ISO-Ländercode, etwa in; Voreinstellung neutral. Eine Ansicht, die der Stil nicht anbietet, bleibt ohne Wirkung.

  • sessionstringOptional

    Kennung der laufenden Sitzung (sess_…), um in derselben Karte den Stil zu wechseln.

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

Erneuert das Kachel-Token einer Sitzung. Läuft die Sitzung noch, ist die Erneuerung kostenlos und billed ist false. Ist sie vorbei (4 Stunden oder 3.000 Kacheln), fehlt sie oder gehört sie zu einem anderen Konto, beginnt eine neue, berechnete Sitzung mit neuer Kennung; billed ist dann true. ttl ist die Gültigkeit des Tokens in Sekunden, tileLimit die Kachelzahl je Sitzung.

Parameter

  • keystring
    Empfohlen

    Öffentlicher Schlüssel (pk_). Alternativ ein Schlüssel im Authorization-Header; sk_-Schlüssel nur dort.

  • sessionstring (body)Optional

    Kennung der Sitzung, deren Token erneuert werden soll, im JSON-Rumpf.

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
}

Nennung

Jede Karte muss ihre Quellen sichtbar nennen. Erzeugen Sie die Karte mit attributionControl: false und fügen Sie MetronAttribution aus dem Client hinzu. Das Steuerelement zeigt unten rechts eine Zeile mit „dbpg METRON Maps“, den Quellenhinweisen aus dem Stil (metadata["dbpg:attribution"]) und einem Link zur Lizenzseite:

  • © OpenStreetMap, mit Link auf openstreetmap.org/copyright. Dieser Hinweis bleibt auch auf schmalen Karten (unter 480 Pixel Breite) sichtbar.
  • © ESA WorldCover
  • © Copernicus DEM
  • Lizenzen: die Lizenzseite mit allen Quellen und den vollständigen Texten. Auf schmalen Karten stehen die beiden vorigen Hinweise nur dort.

Setzen Sie ein eigenes Steuerelement ein, zeigen Sie dieselben Hinweise, mindestens „© OpenStreetMap“ ohne weiteren Klick. Die Kartendaten stehen unter der Open Database License (ODbL).

Fehler

Fehler kommen als JSON mit dem Feld error. Sie kosten nichts.

  • bad_request 400: ein sk_-Schlüssel im Parameter key.
  • invalid_api_key 401: der Schlüssel fehlt oder ist ungültig.
  • insufficient_credits 402: das Guthaben reicht für eine neue Sitzung nicht. Ist das Monatsbudget des Schlüssels erschöpft, lautet der Code key_budget_exhausted.
  • key_origin_denied 403: die Seite ist für diesen pk_-Schlüssel nicht erlaubt, oder die Anfrage nennt keine Seite. Die Meldung nennt die gesehene Seite, damit Sie sie eintragen können.
  • key_scope_denied 403: der Schlüssel darf metron:maps nicht nutzen. Bei IP-Bereichen lautet der Code key_ip_denied.
  • model_not_found 404: unbekannter Stilname. Ist METRON Maps für das Konto nicht freigeschaltet, antwortet die Schnittstelle ebenfalls mit 404.
  • rate_limit_exceeded 429: Ratenlimit des Kontos überschritten. Es zählen Stilabrufe und Erneuerungen, keine Kacheln.
  • service_unavailable 503: der Dienst ist vorübergehend nicht erreichbar.
  • Kacheln: Ein abgelaufenes Token oder eine erschöpfte Sitzung ergibt beim Kachelabruf 401. Der Client erneuert dann selbst; ohne Client rufen Sie /v1/metron/session/refresh auf.