Deutsch

Protomaps-Basemap-Kacheln

Die gesamte Protomaps Basemap, Zoomstufe 0 bis 15, bereitgestellt als ein PMTiles-Archiv über normales HTTP. Richten Sie einen beliebigen PMTiles-Client auf die URL und es funktioniert.

https://tiles.jasontally.com/basemap.pmtiles

Eine gesperrte OpenStreetMap-Kachel oder ein 403 von tile.openstreetmap.org? Hier beginnen.

Ausprobieren

Dasselbe Archiv in drei Stilen. Beim Wechsel des Stils bleiben die bereits geladenen Kacheln erhalten, sodass die Umschaltung sofort erfolgt.

z0

Eigenen Stil erstellen

Ändern Sie eine Farbe oder schalten Sie eine Ebene aus, und die Karte aktualisiert sich sofort. Kopieren Sie anschließend das Stil-JSON – ein normaler MapLibre-Stil, den Sie selbst hosten können. Er verweist auf diese Kacheln und funktioniert daher überall, wo Sie ihn ablegen.

Verwendung

Das Archiv unterstützt HTTP-Range-Requests, sodass jeder PMTiles-Client es lesen kann.

Eins. Eine Karte in die Seite einbetten

Kopieren Sie diese Datei. Das ist das gesamte Beispiel: drei Tags, eine Stil-URL, eine Karte. Beide Bibliotheken haben feste Versionen und stehen unter der BSD-3-Clause-Lizenz; dieselben Dateien werden auch von diesem Host ausgeliefert, falls Sie kein CDN nutzen möchten.

<!doctype html>
<html>
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Basemap</title>
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/maplibre-gl@5.24.0/dist/maplibre-gl.css">
  <script src="https://cdn.jsdelivr.net/npm/maplibre-gl@5.24.0/dist/maplibre-gl.js"></script>
  <script src="https://cdn.jsdelivr.net/npm/pmtiles@3.2.1/dist/pmtiles.js"></script>
  <style>html, body, #map { margin: 0; height: 100%; }</style>
</head>
<body>
  <div id="map"></div>
  <script>
    // Teach MapLibre how to read a PMTiles archive.
    const protocol = new pmtiles.Protocol();
    maplibregl.addProtocol("pmtiles", protocol.tile);

    new maplibregl.Map({
      container: "map",
      style: "https://tiles.jasontally.com/styles/light.json",
      center: [2.35, 48.85],   // Paris
      zoom: 4
    });
  </script>
</body>
</html>

Zwei. Kacheln in einem vorhandenen Stil austauschen

Jeder MapLibre-Stil liest seine Kacheln aus einer Datenquelle. Um diese Kacheln zu nutzen, ändern Sie diese eine url. Sonst ändert sich nichts am Stil.

  "sources": {
    "protomaps": {
      "type": "vector",
-     "url": "pmtiles://https://demo-bucket.protomaps.com/v4.pmtiles",
+     "url": "pmtiles://https://tiles.jasontally.com/basemap.pmtiles",
      "attribution": "<a href=\"https://www.openstreetmap.org/copyright\">&copy; OpenStreetMap contributors</a>"
    }
  }

Oder ändern Sie sie im Code, was nützlich ist, wenn der Stil von einem fremden Server stammt:

// Rewrite every PMTiles source in a style to point at these tiles.
const style = await (await fetch("https://your-server/style.json")).json();

for (const source of Object.values(style.sources)) {
  if (source.url?.startsWith("pmtiles://")) {
    source.url = "pmtiles://https://tiles.jasontally.com/basemap.pmtiles";
  }
}

new maplibregl.Map({ container: "map", style, center: [2.35, 48.85], zoom: 4 });

Drei. Wohin mit dem erstellten Stil

Die Schaltfläche Stil-JSON im Editor oben öffnet den Stil, den diese Karte gerade zeichnet, einschließlich aller Änderungen; der Dialog hat eine Kopierschaltfläche. Es gibt zwei Wege, das Ergebnis zu nutzen, und beide sind gewöhnliche Webseiten.

Speichern Sie ihn als Datei neben Ihrer Seite und lassen Sie style darauf zeigen, so wie die drei Stile auf diesem Host verwendet werden. Wählen Sie diesen Weg, wenn es Ihr eigener Stil ist und er sich zusammen mit Ihrer Website ändert:

// Save the copied JSON as my-basemap.json beside this file.
new maplibregl.Map({
  container: "map",
  style: "my-basemap.json",           // relative, same origin
  center: [2.35, 48.85],
  zoom: 4
});

Oder behalten Sie ihn im HTML – das ist nur eine einzige Datei und erfordert kein weiteres Hosting. Derselbe Stil, nur an einem anderen Ort:

// The copied JSON, pasted straight into the page.
const myStyle = {
  "version": 8,
  "name": "Protomaps Basemap — custom",
  "glyphs": "https://tiles.jasontally.com/font/{fontstack}/{range}.pbf",
  "sprite": "https://tiles.jasontally.com/sprites/v4/light",
  "sources": { /* ... as copied ... */ },
  "layers":  [ /* ... as copied ... */ ]
};

new maplibregl.Map({ container: "map", style: myStyle, zoom: 4 });

Lassen Sie die Zeilen glyphs und sprite unverändert. Sie sind für das Zeichnen der Beschriftungen und Symbole zuständig und verweisen auf diesen Host, sodass ein in Ihre eigene Seite eingefügter Stil überall funktioniert, von wo Sie ihn ausliefern. Richten Sie sie stattdessen auf protomaps.github.io/basemaps-assets, wenn Sie überhaupt nicht von diesem Host abhängen möchten.

Ein Punkt zur Prüfung vor dem Austausch. Dieses Archiv nutzt das Protomaps-Schema v3. Ein für ein anderes Schema geschriebener Stil wird zwar geladen, zeichnet dann aber nichts, weil die Namen der Quellebenen nicht übereinstimmen. Die neun Ebenennamen sind unten aufgeführt, ebenso ein fertiger v3-Stil als Kopiervorlage.

Vier. Schriftarten, Sprites und Bibliotheken

Eine Karte besteht aus den Kacheln, einer glyphs-URL für Text, optional einer sprite-URL für Symbole und den Bibliotheken zum Zeichnen. All das liegt hier unter den jeweils erwarteten Pfaden bereit, sodass eine Karte auf Wunsch von einem einzigen Hostnamen geladen werden kann.

WasURL hierLizenz

Die Dateien für MapLibre und PMTiles liegen auf jsDelivr und hier. Beide URLs funktionieren.

Die letzte Zeile wird von dieser Seite nicht verwendet. Es handelt sich um den Vektor-Renderer für Leaflet, der hier bereitgestellt wird, damit der Austausch nur ein einziges Script-Tag erfordert. Leaflet selbst bleibt auf seinem eigenen CDN.

Zwei Schrift-Stacks, Noto Sans Regular und Noto Sans Medium, aufgeteilt in die 256 Bereiche zu je 256 Codepunkten, die MapLibre anfordert. Alle 256 werden bereitgestellt, nicht nur die lateinischen: Protomaps beschriftet Objekte mit ihrem lokalen Namen, sodass Tokio oder Kairo Bereiche im Zehntausenderbereich benötigen. Stellt man nur bereit, was eine englische Karte nutzt, verschwinden diese Beschriftungen ohne jede Fehlermeldung.

Fünf Sprite-Sheets, eines pro Upstream-Variante, in 1x und 2x. Die Stile unten beziehen ihre Symbole daraus, weshalb diese geladen werden. Wenn Sie Ortsmarken, Autobahnschilder oder interessante Orte (POIs) in einem eigenen Stil nutzen möchten, richten Sie sprite auf die Datei Ihrer Variante. Die Symbolnamen eines Sheets sind in der zugehörigen light.json aufgeführt.

Was die Karte zeichnet und woher jedes Element stammt

Jede Ebene stammt aus einer der neun Quellebenen in diesem Archiv, sodass hierfür kein zweites Archiv nötig ist. Zwei davon verdienen eine besondere Erwähnung, weil beide so aussehen, als würde etwas fehlen, obwohl das nicht der Fall ist:

EbeneStammt ausIn diesem Build?
Flächen, Straßen, Gebäude, Wasser, Landearth, landcover, landuse, water, roads, buildingsja
Orts-, Straßen- und Gewässernamendem Feld name auf denselben Ebenenja
POI-Symbole, Ortsmarkenpois.kind, places sowie dem Spriteja
Straßenschilderroads.shield_textnein. Der aktuell bereitgestellte Build enthält dieses Feld nicht
Hausnummernbuildings.kind=address und buildings.addr_housenumbernein, aus demselben Grund

Es gibt weder ein separates Adressarchiv noch eine eigene Adressebene zum Abrufen. Das Upstream-Projekt legt Adresspunkte innerhalb der Ebene buildings ab, als Objekte mit kind=address und einem addr_housenumber. Dieses Feld kam erst in einem neueren Protomaps-Build hinzu als dem, den diese Karte derzeit ausliefert; die Hausnummernebene ist daher bereits angelegt und aktiviert sich von selbst, sobald die nächste monatliche Aktualisierung die Daten mitbringt. Dasselbe gilt für den Schildtext: Der aktuelle Build enthält shield_text_length – also die Zeichenanzahl einer Straßennummer, nicht deren Inhalt –, sodass ein daraus gezeichnetes Schild auf jeder Autobahn eine leere Form wäre.

Eine eigene Ebene schreiben und einfärben

Eine Ebene besteht aus einem Filter, einer Zoomstufe, einer Form und einer Farbe. Zwei Dinge beim Filter sind typische Stolperfallen, und beide scheitern ohne Fehlermeldung:

Hier also eine Straße, ihr Name und ein Schalter zum Ausblenden der Linie:

{
  "id": "road-major",
  "type": "line",
  "source": "protomaps",
  "source-layer": "roads",            // one of the nine
  "minzoom": 4,                                  // not drawn below this
  "filter": ["==", ["get", "kind"], "major_road"],
  "layout": {
    "line-cap": "round",
    "visibility": "visible"          // "none" to hide it
  },
  "paint": {
    "line-color": "#f7c44d",          // any CSS colour
    "line-width": ["interpolate", ["linear"], ["zoom"], 4, 1.7, 12, 6]
  }
}

Ein Name ist eine Symbolebene, die das Feld name ausliest, mit einem Halo oder ohne Hintergrund. Eine fehlende Glyphe erzeugt keinen Fehler, daher muss der angeforderte Schrift-Stack einer der beiden auf diesem Host sein:

{
  "id": "road-label-major",
  "type": "symbol",
  "source": "protomaps",
  "source-layer": "roads",
  "minzoom": 11,
  "layout": {
    "text-field": ["coalesce", ["get", "name:en"], ["get", "name"]],
    "text-font": ["Noto Sans Medium"],  // or Noto Sans Regular
    "text-size": 10,
    "symbol-placement": "line"       // follow the road
  },
  "paint": {
    "text-color": "#2b2a26",
    "text-halo-color": "#ffffff",
    "text-halo-width": 1.1
  }
}

Eine Ebene, die nichts zeichnet, gilt nicht als Fehler, und MapLibre meldet nicht, welche Prüfung fehlgeschlagen ist. Bleibt Ihre Ebene leer, prüfen Sie in dieser Reihenfolge: den Feldnamen, das minzoom der Ebene, den Schrift-Stack und anschließend den Symbolnamen anhand der light.json des jeweiligen Sprite-Sheets.

Wenn Sie einen Stil haben, dessen Glyphen auf demotiles.maplibre.org zeigen, genügt das Ersetzen dieses Hostnamens. Der Pfad ist bewusst identisch.

"glyphs": "https://tiles.jasontally.com/font/{fontstack}/{range}.pbf",
"sprite": "https://tiles.jasontally.com/sprites/v4/light"

// before, in a style you already have
- "glyphs": "https://demotiles.maplibre.org/font/{fontstack}/{range}.pbf",
+ "glyphs": "https://tiles.jasontally.com/font/{fontstack}/{range}.pbf",

Fordert ein Stil einen Schrift-Stack an, der keiner der beiden oben genannten ist, wird dafür nichts gezeichnet. Die eigenen Stile von Protomaps nutzen Noto Sans Medium für fetten Text; Noto Sans Bold ist in diesem Satz nicht enthalten, weshalb ein Stil, der danach fragt, kommentarlos jede Beschriftung verliert.

Welcher Host schneller ist und was deshalb entschieden wurde. Gemessen statt vermutet: abwechselnde Anfragen, einzeln nacheinander über eine Verbindung, die ersten drei Messwerte verworfen, Time to First Byte getrennt von der Übertragung. In diesem Test antwortete ein CDN bei jeder dieser Dateien 10 bis 45 ms schneller – das erfüllt die 15-%-Regel voll und liegt deutlich über der Messungenauigkeit. Aus diesem Grund werden die Bibliotheken von jsDelivr geladen.

Die Schriftarten und Sprites werden von hier ausgeliefert, obwohl dieselbe Messung zeigt, dass ein CDN etwa 10 ms schneller antworten würde. Das ist eine bewusste Entscheidung, keine Messfrage. Eine Karte von einem einzigen Hostnamen fällt nicht aus, wenn ein fremder Server ausfällt, und ein ausgefallener Glyphen-Server bedeutet eine Karte ohne Beschriftungen. Wenn Ihnen die 10 ms wichtiger sind, richten Sie glyphs auf protomaps.github.io/basemaps-assets/fonts – das funktioniert mit demselben Pfad. Dies sind die Messwerte eines Nutzers aus einer Stadt; der Vergleich lässt sich mit einem Befehl wiederholen.

Fünf. Über Leaflet

L.tileLayer von Leaflet zeichnet Bilder; hier handelt es sich um Vektorkacheln. Eine Leaflet-Karte kann sie dennoch nutzen, und bei beiden Wegen bleiben Ihre Marker, Popups und Bedienelemente erhalten. Beide Umstellungen sind unter Wechsel von OpenStreetMap-Kacheln beschrieben.

Sechs. Das Archiv mit der PMTiles-Bibliothek lesen

Keine Karte, nur Daten. Nützlich für Skripte, Tests und alles, was kein Bild ist.

import { PMTiles, FetchSource } from "pmtiles";

const archive = new PMTiles(new FetchSource("https://tiles.jasontally.com/basemap.pmtiles"));

const header = await archive.getHeader();
console.log(header.minZoom, header.maxZoom);        // 0 15
console.log(header.numAddressedTiles);              // 1431655765

const metadata = await archive.getMetadata();
console.log(metadata.name);                          // "Protomaps Basemap"

const tile = await archive.getZxy(3, 4, 2);          // z, x, y
console.log(tile.data.byteLength);

Beachten Sie die beiden Klassen. FetchSource liest Bytes über HTTP, und PMTiles setzt darauf auf und versteht das Format. FileSource ist das Gegenstück zu FetchSource für lokale Dateien; mit einer URL-Zeichenkette funktioniert es nicht.

Das Archiv ist eine Momentaufnahme, kein Live-Feed. Die Zeitplanung steht unter Wie aktuell sind die Daten?.

Wechsel von OpenStreetMap-Kacheln

Die Sperre durch die Kachel-Nutzungsrichtlinie, der Fehler 403 und was dagegen zu tun ist. Kein Schlüssel, kein Kontingent.

Warum die Karte eine Sperre anzeigt

App is not following the tile usage policy of OpenStreetMap’s volunteer-run servers

General block: app is not following the tile usage policy of openstreetmap volunteer-run servers

403 Forbidden — tile.openstreetmap.org

Die Kachelserver haben dieses Bild absichtlich anstelle der Karte gesendet, gemäß der Kachel-Nutzungsrichtlinie. Es ist keine Störung, und eine Korrektur der URL hebt die Sperre nicht auf.

Was zuerst versucht wird:

Büros, Schulen, VPNs und Mobilfunknetze teilen sich eine Adresse, und Sperren gelten sowohl für Adressen als auch für Anwendungen. Von Ihrer Seite aus lässt sich nicht erkennen, welcher Fall vorliegt.

Fragen Sie diese Server also nicht weiter an. Es gibt drei Wege weg davon.

Leaflet beibehalten

protomaps-leaflet zeichnet Vektorkacheln in Leaflet. Es liest das Archiv selbst und fügt sich als normale Ebene ein, sodass Marker, Popups, GeoJSON und Bedienelemente unverändert bleiben. Eine mit diesem Archiv getestete Kopie liegt hier: https://tiles.jasontally.com/vendor/protomaps-leaflet.js.

Vorher:

<link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css">
<script src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js"></script>

<script>
  const map = L.map("map").setView([48.85, 2.35], 12);

  L.tileLayer("https://tile.openstreetmap.org/{z}/{x}/{y}.png", {
    maxZoom: 19,
    attribution: '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors'
  }).addTo(map);
</script>

Nachher:

<link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css">
<script src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js"></script>
+ <script src="https://tiles.jasontally.com/vendor/protomaps-leaflet.js"></script>

<script>
  const map = L.map("map").setView([48.85, 2.35], 12);

-  L.tileLayer("https://tile.openstreetmap.org/{z}/{x}/{y}.png", { ... }).addTo(map);
+  protomapsL.leafletLayer({
+    url: "https://tiles.jasontally.com/basemap.pmtiles",
+    flavor: "light",
+    lang: "en"
+  }).addTo(map);
</script>

protomaps-leaflet befindet sich im Upstream im Wartungsmodus: Fehlerkorrekturen, keine neuen Funktionen. Für eine bestehende Leaflet-Anwendung reicht das aus. Neue Projekte sollten mit MapLibre GL beginnen.

Leaflet beibehalten, mit MapLibre rendern

@maplibre/maplibre-gl-leaflet legt eine MapLibre-Karte in das Kachel-Pane von Leaflet. Nutzen Sie dies, wenn Sie einen der obigen Stile oder Gelände und Schummerung in einer Anwendung wünschen, die bei Leaflet bleibt.

<link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css">
<link rel="stylesheet" href="https://tiles.jasontally.com/vendor/maplibre-gl.css">
<script src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js"></script>
<script src="https://tiles.jasontally.com/vendor/maplibre-gl.js"></script>
<script src="https://tiles.jasontally.com/vendor/pmtiles.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@maplibre/maplibre-gl-leaflet@0.1.4/dist/leaflet-maplibre-gl.js"></script>

<script>
  // The style's source is pmtiles://, so MapLibre needs the protocol first.
  maplibregl.addProtocol("pmtiles", new pmtiles.Protocol().tile);

  const map = L.map("map", { minZoom: 1 }).setView([48.85, 2.35], 12);

  const gl = L.maplibreGL({
    style: "https://tiles.jasontally.com/styles/light.json"
  }).addTo(map);

  // gl.getMaplibreMap() is the MapLibre map, for sources and layers.
</script>

Wechsel zu MapLibre GL

Eine Bibliothek, kein Adapter, und die Stile von oben funktionieren unverändert. Die vollständige Seite steht unter Eins. Eine Karte in die Seite einbetten. Der Wechsel besteht hauptsächlich im Vertauschen der Koordinatenreihenfolge:

LeafletMapLibre GL
L.map("map").setView([lat, lng], z)new maplibregl.Map({ container: "map", center: [lng, lat], zoom: z })
L.tileLayer(url).addTo(map)ein Stil mit einer Vektor-Datenquelle; siehe oben
L.marker([lat, lng]).bindPopup(html)new maplibregl.Marker().setLngLat([lng, lat]).setPopup(new maplibregl.Popup().setHTML(html))
L.geoJSON(data)addSource(id, { type: "geojson", data }), danach addLayer
L.control.scale()new maplibregl.ScaleControl()
map.invalidateSize()map.resize()

setView([lat, lng]) erwartet zuerst den Breitengrad; jeder MapLibre-Aufruf erwartet [lng, lat]. Liegt eine Karte auf der falschen Halbkugel, liegt es daran und nicht an den Kacheln. Datenquellen und Ebenen, die vor dem Laden des Stils hinzugefügt werden, gehen ohne Fehlermeldung verloren; fügen Sie sie daher in map.on("load", …) hinzu.

“archive contains MVT vector tiles, but leafletRasterLayer is for displaying raster tiles”

Das stammt von pmtiles.leafletRasterLayer, das Raster-PMTiles als Bilder zeichnet. Hier handelt es sich um Vektorkacheln, weshalb sie abgelehnt werden. Keine Option ändert das, und es gibt hier keine Rasterkopie. Verwenden Sie eine der oben genannten Möglichkeiten.

“download.openstreetmap.fr returned 403”

Das ist ein Extrakt- und Replikations-Mirror, kein Kachelserver. Im Oktober 2026 hat er nach missbräuchlichen Downloads Adressen gesperrt, und die Betreiber kündigten an, den Zugriff im Einzelfall wieder freizugeben. Nichts hier benötigt diesen Server: Dieses Archiv stammt aus Protomaps-Releases, sodass Sie keine .osm.pbf-Dateien selbst zusammenbauen müssen. Falls Sie OSM-Daten abrufen, nutzen Sie einen periodischen Extrakt statt des Minuten-Streams.

Stile

Dieselben Kacheln, andere Farben. Einen Stil auswählen, kopieren, anpassen – er gehört Ihnen.

StilAussehenDatei

Was in den Kacheln steckt

Beim Laden der Seite direkt aus den Metadaten des Archivs gelesen. Dies sind die Ebenennamen, die ein Stil verwenden muss.

QuellebeneZoomstufeFelder
wird geladen…

Was dieser Dienst nicht ist

Klare Antworten, damit es später keine Überraschungen gibt.

Wie aktuell sind die Daten?

Die Kacheln sind eine Kopie der Protomaps Basemap und werden einmal im Monat neu gebaut.

Stil-JSON

open raw