# Live traffic | Rijwind docs

# Live traffic

The live traffic layer adds real-time road conditions on top of the
basemap: roads coloured by how freely traffic is flowing, plus an overlay
of incidents, roadworks, and closures. It's built from official national
road-authority data, normalised into one consistent schema.

Coverage at launch is the **Netherlands**; more countries roll out on the
same layer, so a map that enables traffic today picks them up automatically
as they go live.

## How it works

The road geometry loads once. A small live-state file — a compact map of
`road segment → current speed and congestion level` — is published about
once a minute and fetched by the browser, then painted onto the roads
client-side. There's no tile re-fetch and no restyle when conditions
change, so the layer stays smooth and cheap: a refresh moves only a few
hundred kilobytes, not a whole tileset.

Incidents and roadworks are delivered as a lightweight overlay with the
same near-real-time cadence.

## Quickstart

The `@rijwind/sdk` `Map` wires everything up from your API key:

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

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

const map = new Map({
  container: "map",
  center: [4.9, 52.37],
  zoom: 9,
  traffic: true,
});
```

Prefer to toggle it at runtime — say, behind a "Traffic" button?

```ts
map.enableTraffic();                          // all available countries
map.enableTraffic({ countries: ["NL"] });     // just the Netherlands
map.enableTraffic({ incidents: false });      // flow only, no incident overlay
map.disableTraffic();
```

The layer keeps its data fresh on its own and pauses polling while the
browser tab is hidden. Required source attribution is added to the map's
attribution control for you.

## What the colours mean

Roads are coloured by a congestion level derived from the current speed
relative to that road's free-flow speed:

| Colour | Meaning              |
| ------ | -------------------- |
| Green  | Free-flowing         |
| Yellow | Moderate             |
| Orange | Slow                 |
| Red    | Congested / jammed   |

A road with no live measurement keeps its normal basemap styling rather
than being coloured.

## Billing

The traffic layer is billed **1 unit per map session** — one charge no
matter how long the map stays open or how many times the live state
refreshes — on top of the 1 unit for the basemap session it rides on. It's
drawn from the same monthly unit pool as every other endpoint; there's no
separate traffic plan or per-request tile metering. Enabling traffic later
in an existing session adds the one extra unit; refreshes are always free.

See [Quotas & rate limits](/quotas) for the full cost table.

## Without the SDK

The layer is plain MapLibre underneath: a vector tileset for the road
geometry (joined to live data with `setFeatureState`) and a GeoJSON source
for incidents. Request `GET /tiles/v1/token?session=<id>&traffic=NL` — the
response includes a `traffic` block with the CDN base URL and a signed
query string valid for every traffic artifact. See the
[API reference](/api) for the response shape. The SDK is the supported
path; hand-wiring is possible but you own the polling and the
feature-state join yourself.