Skip to main content

Response

Both GET /map.{svg,png} and POST /render/map return the same response structure.

Content types​

FormatContent-Type
SVGimage/svg+xml
PNGimage/png

The format is determined by the format parameter (or the URL extension for GET). SVG is the default.

Caching​

GET endpoint​

GET responses include:

Cache-Control: public, max-age=31536000, immutable
ETag: "<sha1-of-normalised-request>"

The ETag value is a SHA-1 hash of the normalised request parameters (scope, theme, data values, width, projection, and all other inputs). Two requests with semantically identical inputs — regardless of parameter order or capitalisation — produce the same ETag.

POST endpoint​

POST responses include an ETag header with the same SHA-1 semantics, but do not include Cache-Control. The response is served from the in-process LRU cache when the same normalised input has been seen before, but clients and CDNs are not instructed to cache POST responses.

Conditional requests​

The GET endpoint supports If-None-Match. If you send the ETag value back on a subsequent request, the server returns 304 Not Modified with no body, skipping the render pipeline entirely:

GET /map.png?scope=world&data=US:200,CN:150&theme=dark
→ 200 OK
   ETag: "a3f9c2..."
   Cache-Control: public, max-age=31536000, immutable

GET /map.png?scope=world&data=US:200,CN:150&theme=dark
   If-None-Match: "a3f9c2..."
→ 304 Not Modified

The POST endpoint returns an ETag but does not currently support If-None-Match conditional requests.

X-Cache header​

Both endpoints return X-Cache: HIT or X-Cache: MISS to indicate whether the response was served from the in-process LRU cache.

Cloudflare edge caching (GET only)​

When GET requests are served behind Cloudflare, the Cache-Control: public, max-age=31536000, immutable header causes Cloudflare to cache the response at the edge. Subsequent requests for the same URL are served directly from Cloudflare's CDN without reaching the origin server. Because all map parameters are encoded in the URL, each unique map is a separate cache entry.

X-Geo-Warnings​

When the request includes region IDs or route endpoints that are not found in the map topology, the server renders the map using the IDs it does recognise and returns the unknown ones in a warning header:

X-Geo-Warnings: unknown-ids:XX,YY; unknown-routes:AA>BB
  • unknown-ids — region IDs that appeared in data, regions, patterns, annotations, or proportional but were not in the topology. Up to 50 IDs are listed.
  • unknown-routes — route endpoints that could not be resolved to coordinates. Up to 50 route pairs are listed.

The response is still 200 OK — your map renders with whatever IDs did match. Check this header to diagnose missing regions.