Copy page

Tiles & basemaps

Vector basemap | Rijwind docs

Vector basemap

The Rijwind basemap is delivered as PMTiles — a single addressable file served from a global CDN. MapLibre GL JS fetches byte ranges from it as the user pans and zooms; you don't run a tile server.

How it works

1. Your app calls GET /v1/tiles-token from the browser. It returns a signed URL bound to the requester's IP and expiring after one hour by default.
2. You fetch a Rijwind style JSON, substitute the signed URL into it, and pass the result to MapLibre.
3. MapLibre handles byte-range requests against the file from then on.

Fetch a fresh signed URL on each page load.

Quota cost: 1 unit per token issued — a "tile session", not one tile.

Ready-made styles

Five themes are hosted and ready to use:

Theme	URL
light	https://rijwind.com/styles/light.json
dark	https://rijwind.com/styles/dark.json
grayscale	https://rijwind.com/styles/grayscale.json
white	https://rijwind.com/styles/white.json
black	https://rijwind.com/styles/black.json

The font glyphs and sprite atlases the styles reference are hosted at cdn.rijwind.com/basemap/... — same edge cache as the tile bytes, so the second visitor to a page using the same theme pays no origin latency for the assets.

Each style references pmtiles://{{TILE_URL}} as the tile source — a templated placeholder. Replace it with the signed URL you got from /v1/tiles-token before handing the style to MapLibre.

MapLibre example

Code
<link rel="stylesheet" href="https://unpkg.com/maplibre-gl/dist/maplibre-gl.css" />
<script src="https://unpkg.com/maplibre-gl/dist/maplibre-gl.js"></script>
<script src="https://unpkg.com/pmtiles/dist/pmtiles.js"></script>

<div id="map" style="width: 100%; height: 100vh;"></div>

<script type="module">
  // 1. Ask Rijwind for a signed tile URL.
  const tokenRes = await fetch("https://api.rijwind.com/v1/tiles-token", {
    headers: { Authorization: "Bearer rw_live_•••YOUR_KEY•••" },
  });
  const { url: tileUrl } = await tokenRes.json();

  // 2. Fetch the style and inject the tile URL.
  const styleRes = await fetch("https://rijwind.com/styles/light.json");
  const styleText = await styleRes.text();
  const style = JSON.parse(styleText.replaceAll("{{TILE_URL}}", tileUrl));

  // 3. Register the PMTiles protocol and boot the map.
  const protocol = new pmtiles.Protocol();
  maplibregl.addProtocol("pmtiles", protocol.tile);

  const map = new maplibregl.Map({
    container: "map",
    style,
    center: [4.9041, 52.3676],
    zoom: 10,
  });
</script>

That's the full integration. No tile server to operate, no style file to maintain locally, no font/sprite hosting on your side.

Custom styling

If you need to colour the basemap to match your product palette, fetch one of the ready-made styles, mutate the layers array, and pass the result to MapLibre. The layer ids are stable across releases — see the JSON itself for the exact set. Background colour, water fill, road casings, and label colours are the usual things to tune.

What about raster tiles?

We don't serve raster tiles in v1. If you need a raster basemap for a print pipeline or a legacy GIS client, render the vector basemap to a PNG on your side. Get in touch if this becomes a pain point.