Skip to main content

FAQ

Caching​

How is rendering cached?

Every response carries Cache-Control: public, max-age=31536000, immutable plus an ETag (SHA-1 of the normalised request parameters). Re-using the exact same URL is effectively free — the response is served from cache at the CDN edge (Cloudflare) or from the client's browser cache without hitting the origin at all.

If you send If-None-Match with the previous ETag and the map has not changed, the server returns 304 Not Modified with no body.

Does changing a parameter bust the cache?

Yes. Any change to any query parameter produces a different cache key and renders a fresh map. Normalisation happens before hashing, so equivalent values (e.g. theme=light vs the default) that resolve to the same output share the same cache key.

Rate limits​

Are there rate limits?

Not in the public preview (as of 2026-05-25). The service is free to use. Please be considerate: reuse URLs so CDN cache does the work rather than triggering repeated renders. If you need to generate a large batch of maps, space requests out rather than hammering them concurrently.

Rate limiting will be introduced before the service leaves preview.

Request limits​

What is the maximum request body size?

4 MB for POST /render/map. Requests larger than this are rejected with 413 Request Entity Too Large. If you are hitting this limit, split your data across multiple requests or reduce the number of regions/markers/routes per call.

How many regions can I render per request?

5,000 regions maximum. Each region can carry an optional value, color, pattern, and annotation.

How many markers can I add per request?

1,000 markers maximum.

How many routes can I add per request?

500 routes maximum.

What are the valid coordinate ranges?

  • Latitude: -90 to +90
  • Longitude: -180 to +180

What are the maximum dimensions?

Width and height are each capped at 8,000 px. Default width is 1,200 px; height defaults to null (auto-fitted to the scope's aspect ratio).

Formats​

Should I use SVG or PNG?

Use SVG whenever the host environment accepts it — it is smaller, infinitely scalable, and search-engine-indexable. SVG is the default.

Use PNG for:

  • Slack, Discord, Notion, and other tools that preview raster images.
  • Open Graph / Twitter card <meta property="og:image"> tags.
  • Email clients.
  • Anywhere that requires a fixed pixel dimension.

See Size and format for the format, width, and height parameters.

Data and geometry​

Can I get the raw GeoJSON?

No. maproll is a rendering service, not a geometry distribution service. Raw geometry is never exposed via the API. If you need the underlying geo data, the OSM exports used to build the assets are publicly available from the OpenStreetMap project.

Hosting and self-hosting​

Can I run my own instance?

TBD. We are evaluating a self-hosted option. Reach out at [email protected] to discuss your use case.