Copy page

Maps & styles

Static maps | Rijwind docs

Static maps

A static map is a map rendered to an image — a PNG, WebP, or JPEG you request with a plain URL and drop straight into an <img> tag, an email, a PDF, or a social card. No JavaScript, no interactive map, just a picture of exactly the view you ask for.

Code
<img
  src="https://api.rijwind.com/styles/v1/light/static/4.9041,52.3676,12/800x500.png?key=YOUR_KEY"
  width="800"
  height="500"
  alt="Amsterdam"
/>

Cost: 1 unit per image, or 2 units for a High-DPI (@2x) image — drawn from the same monthly pool as every other endpoint.

URL anatomy

Code
https://api.rijwind.com/styles/v1/{style}/static/{position}/{size}?key=YOUR_KEY

Part	Values
{style}	light, dark, grayscale, white, or black.
{position}	{lon},{lat},{zoom} — optionally ,{bearing},{pitch}. Or a bounding box [{minLon},{minLat},{maxLon},{maxLat}]. Or auto.
{size}	{width}x{height} — optionally @2x for High-DPI, optionally .png, .webp, or .jpg (default png). Max 1280 per side.

The API key rides the query string as ?key= (an <img> tag can't send an Authorization header).

Choosing the view

You have three ways to frame the map:

• Center + zoom — 4.9041,52.3676,12. The classic way.

• Bounding box — give the box to fit as [{minLon},{minLat},{maxLon},{maxLat}] and we pick the center and zoom that frame it:

  Code
  /styles/v1/light/static/[4.85,52.34,4.95,52.40]/800x500.png?key=YOUR_KEY

• Auto — use the literal auto for the position and we frame the map around your overlays:

  Code
  /styles/v1/light/static/auto/800x500.png?marker=4.9,52.37&marker=4.95,52.40&key=YOUR_KEY

Add ,{bearing} (rotation, degrees) and ,{pitch} (tilt, 0–60°) after the zoom to rotate or tilt the camera: 4.9041,52.3676,12,30,45.

Overlays

Overlays ride the query string.

Markers

Code
marker={lon},{lat}|{color}|{size}|{label}

color is a hex color without the #; size is s, m, or l; label is optional. Repeat marker= for more than one. All fields after the coordinate are optional.

Code
?marker=4.9041,52.3676|ff0000|l|A&marker=4.95,52.40|0066ff|s

Paths

Code
path=stroke:{color}|width:{n}|opacity:{n}|fill:{color}|fillOpacity:{n}|{geometry}

The style fields are named (key:value), all optional, in any order. {geometry} is either an encoded polyline (enc:…, precision 5) or a lon,lat;lon,lat;… list. Adding a fill turns the path into a filled shape.

Code
?path=stroke:0066ff|width:4|4.9041,52.3676;4.95,52.40;4.93,52.42

Circle

Draw a circle of a given radius (metres) around the center — its fields are named too, with radius required:

Code
circle=radius:{meters}|stroke:{color}|strokeWidth:{n}|fill:{color}|fillOpacity:{n}

Code
?circle=radius:1000|stroke:0066ff|strokeWidth:2|fill:0066ff|fillOpacity:0.15

Padding & attribution

When fitting a bounding box or auto, add inner padding (px) so overlays don't touch the edges — one value for all sides, or 1–4 CSS-order values (top,right,bottom,left):

Code
?padding=40            # all sides
?padding=40,20,40,20   # top, right, bottom, left

The OpenStreetMap credit is drawn in the bottom-right by default. Move it with attribution=bottomleft|topleft|topright, or set attribution=false to omit it — in which case you must credit OpenStreetMap somewhere else in your product (the data licence requires it).

Language

Labels show local/native names by default (Den Haag, Bruxelles, Köln). Add lang to render them in a specific language instead — names without that language fall back to the local name:

Code
?lang=en   # English where available
?lang=de   # German

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. Use lang=local (the default) for native names.

Hiding labels

Basemap labels — place names, road labels, road shields, and POI icons — are drawn by default. Set labels=false to hide all of them for a clean, label-free map, handy as a backdrop for your own overlays:

Code
?labels=false

Markers you add keep their own labels — labels=false only strips the basemap, not your overlays.

With the SDK

@rijwind/sdk builds the URL for you — pure string building, so it works in Node and the browser:

Code
import { staticMapUrl, config } from '@rijwind/sdk';
config.apiKey = 'rw_live_…';

const url = staticMapUrl({
  center: [4.9041, 52.3676],
  zoom: 12,
  size: [800, 500],
  style: 'light',
  markers: [{ lon: 4.9041, lat: 52.3676, color: '#ff0000', size: 'l', label: 'A' }],
  circle: { radiusMeters: 1000, fillColor: '#0066ff', fillOpacity: 0.15 },
});
// <img src={url} width={800} height={500} alt="map" />

Limits

Limit	Value
Image size	1280 px per side (2560 with @2x)
Markers	50 per image
Path vertices	500 total per image
Pitch	0–60°
Circle radius	up to 5,000,000 m

For overlay sets too large to fit in a URL, POST the same parameters as a JSON body to /styles/v1/{style}/static (this returns the image, so it can't be used directly in an <img> tag).

Keep your key in mind. A static-map URL contains your key, so anyone who can see the image can reuse the URL. For keys used in public <img> tags, leave the project's allowed-origins list empty and rely on your monthly quota — see Authentication.