# 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.

```html
<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

```
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:

  ```
  /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:

  ```
  /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

```
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.

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

### Paths

```
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.

```
?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:

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

```
?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`):

```
?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:

```
?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:

```
?labels=false
```

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

## With the SDK

[`@rijwind/sdk`](https://www.npmjs.com/package/@rijwind/sdk) builds the URL
for you — pure string building, so it works in Node and the browser:

```ts
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](/authentication).