Copy page

Maps & styles

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

The quickest path is the @rijwind/sdk Map — it renders the basemap, handles tile delivery, and keeps everything fresh from a single API key. Under the hood it's MapLibre GL JS, so every MapLibre method and option you already know works unchanged.

MapLibre fetches byte ranges from the PMTiles file as the user pans and zooms; you don't run a tile server.

How tile billing works

Tiles are billed per map session, not per tile — roughly one unit per map view. Pan, zoom, and switch themes as much as you like within a session; it stays one unit. A session covers a map for about an hour, so a typical visitor loading your map costs a single unit.

The SDK takes care of this automatically — one map is one session, kept alive for as long as it's on screen. Integrating without the SDK? See the API reference for the session parameter so your usage is counted as sessions too.

Ready-made styles

The Streets basemap ships in five colour variants, plus an Outdoor style (hillshade + contour lines — see Outdoor & contour lines). The full catalog is on Styles & tilesets.

Style	URL
light (default)	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
outdoor	https://rijwind.com/styles/outdoor.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.

You can pass a theme by name to the SDK (below), or fetch the JSON and tweak it yourself — see Custom styling. The styles reference pmtiles://{{TILE_URL}} as the tile source, a placeholder the SDK substitutes for you.

Quickstart

Code
npm install @rijwind/sdk

Code
import { Map, MapStyle, config } from "@rijwind/sdk";
import "@rijwind/sdk/style.css";

config.apiKey = "rw_live_•••YOUR_KEY•••";

const map = new Map({
  container: "map",
  style: MapStyle.LIGHT, // LIGHT · DARK · GRAYSCALE · WHITE · BLACK
  center: [4.9041, 52.3676],
  zoom: 10,
});

// Tear-down (the tile session is cleaned up with the map):
// map.remove();

That's the full integration. Map extends MapLibre GL JS, so markers, popups, layers, and events all work as usual. No tile server to operate, no signed URLs to manage, no font or sprite hosting on your side — and the map keeps working for as long as it's open.

To colour the basemap, pass your own style URL or object instead of a MapStyle (see Custom styling).

Label language

Labels show local/native names by default. Set language to render them in a specific language (names without it fall back to local), and switch at runtime with setLanguage — no flicker:

Code
const map = new Map({ container: "map", language: "en" });

// later — a language toggle, say:
map.setLanguage("nl"); // or "de", "fr", … or "local" for native names

Supported codes: ar, bg, cs, da, de, el, en, es, et, fa, fi, fr, ga, he, hi, hr, hu, id, it, ja, ko, lt, lv, mr, mt, ne, nl, no, pl, pt, ro, ru, sk, sl, sv, tr, uk, ur, vi, zh-Hans, zh-Hant. Set a default for every map with config.language = "en".

Without the SDK

Prefer raw MapLibre, or already have a map configured? Call GET /tiles/v1/token yourself and feed the returned URL to MapLibre's pmtiles:// protocol. You then keep the URL fresh as it rotates, and pass a session id so your usage groups into sessions — both are documented in the API reference.

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.

Terrain and hillshade

The basemap can render shaded relief (hillshade) and optional tilted 3D terrain from elevation data. Terrain is part of the same map session as the basemap, so it adds no extra quota cost.

Code
import { Map } from "@rijwind/sdk";
import "@rijwind/sdk/style.css";

const map = new Map({
  container: "map",
  center: [6.87, 45.92], // somewhere with relief
  zoom: 12,
  terrain: true, // shaded relief
});

// 3D terrain — wire this to your own button
map.on("load", () => map.setTerrain3D(true));

terrain: true adds hillshade; setTerrain3D(true) tilts the map and raises the relief (setTerrain3D(false) flattens it again).

Terrain without the SDK

The GET /tiles/v1/token response includes a terrainUrl next to the basemap url. Register it as a raster-dem source with the terrarium encoding and add a hillshade layer (or call map.setTerrain):

Code
map.addSource("terrain", {
  type: "raster-dem",
  url: "pmtiles://<terrainUrl from /tiles/v1/token>",
  tileSize: 512,
  encoding: "terrarium",
  maxzoom: 12,
});
map.addLayer({ id: "hillshade", type: "hillshade", source: "terrain" });
// 3D:
map.setTerrain({ source: "terrain", exaggeration: 1.2 });

When you render terrain, keep the terrain data credit shown on the map (the SDK adds it for you via the attribution control). To read elevation values — points or a route profile — use the Elevation API instead.

Outdoor & contour lines

The Outdoor style is Streets plus shaded relief and elevation contour lines — built for cycling, hiking, and the outdoors. With the SDK it's one line:

Code
import { Map, MapStyle } from "@rijwind/sdk";
import "@rijwind/sdk/style.css";

const map = new Map({
  container: "map",
  style: MapStyle.OUTDOOR, // hillshade + contours, on automatically
  center: [6.87, 45.92],
  zoom: 12,
});

The contour lines are generated in the browser from the elevation data, so there's no contour tileset to load and they stay crisp at every zoom — and because they ride the same map session as the basemap, they add no extra quota cost.

Outdoor without the SDK

Generate the contours yourself with maplibre-contour, pointed at the Rijwind terrain tiles. The contour generator runs in a web worker and can't send an Authorization header, so the key rides the query string — use an origin-restricted key. The terrain tiles are Terrarium-encoded and free (part of the map session).

Code
import mlcontour from "maplibre-contour";

const demSource = new mlcontour.DemSource({
  url: "https://api.rijwind.com/tiles/v1/terrain/{z}/{x}/{y}?key=YOUR_KEY",
  encoding: "terrarium",
  maxzoom: 12,
  worker: true,
});
demSource.setupMaplibre(maplibregl);

map.addSource("contours", {
  type: "vector",
  tiles: [
    demSource.contourProtocolUrl({
      // [minor, major] line spacing in metres, per zoom (coarse on purpose so
      // flat areas near sea level stay uncluttered)
      thresholds: { 11: [100, 500], 13: [50, 250] },
      elevationKey: "ele",
      levelKey: "level",
      contourLayer: "contours",
    }),
  ],
  maxzoom: 15,
});

map.addLayer({
  id: "contour-lines",
  type: "line",
  source: "contours",
  "source-layer": "contours",
  paint: {
    "line-color": "rgba(150,116,74,0.5)",
    "line-width": ["match", ["get", "level"], 1, 1.1, 0.5],
  },
});

map.addLayer({
  id: "contour-labels",
  type: "symbol",
  source: "contours",
  "source-layer": "contours",
  filter: [">", ["get", "level"], 0],
  layout: {
    "symbol-placement": "line",
    "text-size": 11,
    "text-field": ["concat", ["number-format", ["get", "ele"], {}], " m"],
    "text-font": ["Noto Sans Regular"],
  },
  paint: {
    "text-color": "#6f5535",
    "text-halo-color": "rgba(255,255,255,0.85)",
    "text-halo-width": 1.2,
  },
});

Pair this with the hillshade snippet above for the full Outdoor look.

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.