Skip to main content

FAQ

Caching​

How is rendering cached?

Every GET /map.{svg,png} 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.

Two exceptions. A request that presents a valid API key is returned private, no-store, so an un-watermarked render can never be stored by a shared cache and served to anonymous callers of the same URL. And POST /render/map returns an ETag and X-Cache, but no Cache-Control — the JSON endpoint is not the cache-friendly one, which is what GET is for.

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?

The API implements none (verified against the source on 2026-09-12). 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 (4,194,304 bytes). The renderer and the reverse proxy in front of api.maproll.io are set to the same ceiling, so that is the limit in practice. A larger body is rejected by the proxy with a plain-HTML 413 Request Entity Too Large rather than the API's usual JSON error shape. If you are hitting it, 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.

Can I find out which region IDs a scope accepts?

Yes. GET /scopes lists every scope, and GET /scopes/<scope>/regions returns the region IDs that scope can draw — IDs only, never geometry or names. Use it to validate a dataset before turning it into a render URL, since a row keyed to an ID the topology does not have is skipped silently at render time and reported only in X-Geo-Warnings.

Hosting and self-hosting​

Can I run my own instance?

TBD. We are evaluating a self-hosted option. Reach out at cst@riskline.com to discuss your use case.