MapPoster API Reference

Render print-ready custom map posters over HTTP. Get an API key →

Base URL & authentication

All requests go to https://api.mapposter.xyz over HTTPS. Authenticate with your secret key as a Bearer token:

Authorization: Bearer mpk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Keep your key server-side. If it leaks, rotate it from the dashboard (or POST /v1/keys/rotate).

For code generators and AI agents: the API's OpenAPI 3.1 description, and how agents get a key, in auth.md.

Plans & limits

Plan	Included	Resets
Starter	100 renders / month	1st of month (UTC)
Pro	1,000 renders / month	1st of month (UTC)
Business	5,000 renders / month	1st of month (UTC)
Single Render	1 render credit	—

Over-quota requests return 429. Responses include X-RateLimit-Limit and X-RateLimit-Remaining headers.

Licence

While your Starter, Pro or Business subscription is active, posters you render with an artistic theme carry a commercial use licence: you may sell them as prints and physical products and use them for clients and marketing. Posters you have put to commercial use by the time the subscription ends keep their licence afterwards. Single Render credits cover personal and limited commercial use. The map-tile styles standard and satellite are for personal use only. Keep the map credit printed on each poster, and repeat it in product listings and on packaging. Full terms: Terms of Service, section 3.

POST/v1/render

Generates a poster and returns a URL to the stored file. Rendering takes a few seconds.

Request body

Field	Type	Notes
`lat`	number	Required. Center latitude.
`lon`	number	Required. Center longitude.
`zoom`	number	Map zoom (e.g. 11–15).
`theme`	string	Theme key (e.g. `blueprint_classic`, `paper_heritage`, `midnight_dark`, `satellite`). The map-tile styles `standard` and `satellite` need `renderMode: "tile"`. The city maps `midnight_dark`, `minimal_white` and `modern_voyager` show street and place names unless `params.showLabels` is `false`; the old keys `dark`, `minimal` and `voyager` still work and map to them.
`renderMode`	string	`artistic` (default) or `tile`.
`city`	string	City label text on the poster.
`country`	string	Sub-label text.
`width`, `height`	number	Poster aspect (px), e.g. 1080 × 1350.
`format`	string	`png` (default), `jpeg`, `webp`, `pdf`, `svg`. `svg` is true vector for artistic themes (fonts embedded), sharp at any size, but leaves map labels out; for the map-tile styles it wraps a raster image.
`maxDimension`	number	Cap on the longest edge in px. Default & server max 4096.
`preview`	boolean	Also return a 640px WebP preview as `preview: { mime, data }` (base64), e.g. to show the poster inline in a chat.
`params`	object	Any additional state fields by name (markers, route, fonts, mat, layer toggles…).
`rawParams`	object	Escape hatch: set share-URL params directly by short code.

Example

curl https://api.mapposter.xyz/v1/render \
  -H "Authorization: Bearer mpk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "lat": 52.3702,
    "lon": 4.8952,
    "zoom": 13,
    "renderMode": "artistic",
    "theme": "blueprint_classic",
    "city": "AMSTERDAM",
    "country": "NETHERLANDS",
    "width": 1080,
    "height": 1350,
    "format": "png"
  }'

Response `200`

{
  "id": "a1b2c3d4-…",
  "url": "https://api.mapposter.xyz/files/renders/<key>/<id>.png",
  "format": "png",
  "bytes": 5242880,
  "usage": { "used": 7, "quota": 100, "remaining": 93 },
  "provenance": {
    "id": "a1b2c3d4-…",
    "issued": "2026-06-10T12:00:00.000Z",
    "sha256": "<sha-256 of the rendered bytes>",
    "signature": "<hmac signature>"
  }
}

Errors

Status	Meaning
`400`	Invalid request body (e.g. missing `lat`/`lon` or unsupported format).
`401`	Missing or invalid API key.
`402`	Out of render credits (Single Render plan).
`503`	Renderer busy or out of browser time — retry later.
`403`	Key suspended or revoked (e.g. payment lapsed).
`429`	Monthly quota exceeded.
`502`	Render failed — safe to retry.

GET/v1/me

Returns plan, status, and current-period usage for the calling key.

curl https://api.mapposter.xyz/v1/me -H "Authorization: Bearer mpk_live_xxx"

POST/v1/keys/rotate

Issues a new secret for your key and immediately invalidates the old one. The new key is returned once in the response.

Provenance & verification

Every render is signed by MapPoster. The signature is embedded in the file metadata (a PNG tEXt chunk / SVG <metadata> element), in the stored object's metadata, and returned as the provenance object. To confirm a poster genuinely came from MapPoster, POST that record back:

POST/v1/verify

curl https://api.mapposter.xyz/v1/verify \
  -H "Content-Type: application/json" \
  -d '{"v":1,"id":"a1b2c3d4-…","plan":"pro","issued":"2026-06-10T12:00:00.000Z","sha256":"…","sig":"…"}'

# → { "valid": true, "id": "a1b2c3d4-…", "issued": "…", "plan": "pro", "logged": true }

Note: file metadata can be stripped by re-encoding. The signature proves authenticity for intact files; logged:true additionally confirms the render id exists in our records.