Size and format

maproll renders to either SVG or PNG. You control the canvas width, and optionally the height. When height is omitted the server derives it from the projection's natural aspect ratio.

Examples

Default size — 1200 px wide, height auto

https://api.maproll.io/map.svg?scope=world&data=US:100,CN:80&theme=dark&width=1200

Thumbnail — 300 px wide

https://api.maproll.io/map.svg?scope=world&data=US:100,CN:80&theme=dark&width=300

Explicit height — projection fitted to the exact canvas

https://api.maproll.io/map.svg?scope=world&data=US:100,CN:80&theme=dark&width=800&height=400

PNG output — same URL, .png extension

https://api.maproll.io/map.png?scope=world&data=US:100,CN:80&theme=dark&width=800

Parameters

Param	Type	Default	Allowed	Notes
width	integer	1200	1 – 8000	Output width in pixels.
height	integer	auto	1 – 8000	Output height in pixels. Omit to auto-compute from the projection's aspect ratio.
format	string	endpoint-dependent	svg, png	Can also be set via the URL extension: /map.svg or /map.png.

The format parameter is redundant when using the GET endpoint — the extension (/map.svg vs /map.png) already sets the format. Use the format field in the POST body when you want PNG output from POST /render/map.

SVG vs PNG

	SVG	PNG
Content-type	image/svg+xml	image/png
File size	Scales with geographic complexity, not pixel dimensions. A world map is typically 200–500 KB.	Scales with pixel count. A 1200 px wide PNG is typically 200–400 KB.
Scalability	Infinitely scalable — correct at any zoom level or display DPI.	Fixed resolution.
Browser support	All modern browsers, including <img src="...svg"> embeds.	Universal.
Email / Slack	Many email clients and Slack unfurls do not render SVG.	Works everywhere.
Open Graph / Twitter cards	Not accepted by most social platforms.	Required for OG og:image tags.
Accessibility	<title> tooltips added via the annotations= parameter are machine-readable.	Raster — no semantic layer.
Caching	Immutable — same URL always returns the same content.	Same.

Choose SVG when: embedding in HTML, Markdown, or a tool that renders inline SVG; when you want infinite zoom; or when you want tooltip annotations.

Choose PNG when: the embed context does not accept SVG (Slack, Discord, email, OG cards, Notion image embeds, some CMS thumbnail pipelines).

Aspect ratio

When height is omitted, the server runs a two-pass projection fit:

1. Fit the projection to the requested width.
2. Compute the projected bounding-box height and use that as the canvas height.

This produces the projection's natural aspect ratio exactly. For example, a world scope at width=1200 with naturalEarth1 returns height 526 — the correct Natural Earth ratio. Forcing height=600 would slightly distort the projection fit to fill the extra vertical space.

File-size guidance

Scenario	Typical SVG size	Typical PNG size
World map, low detail	200–300 KB	150–300 KB at 1200 px
World map, medium detail	400–600 KB	same
Regional scope (e.g. RO), medium detail	80–150 KB	80–200 KB at 1200 px
Width 300 px (thumbnail)	same SVG	30–60 KB
Width 2400 px (presentation)	same SVG	600 KB – 1.2 MB

SVG size is independent of pixel dimensions; PNG size scales linearly with pixel area.

All responses carry Cache-Control: public, max-age=31536000, immutable — the URL is the cache key, so a 2400 px render is cached separately from a 1200 px render of the same data.

Notes

• width and height must be positive integers. Values outside 1–8000 return 400.
• Setting both width and height to large values (e.g. 4000×3000) is valid but will produce a large PNG and a slower render. SVG cost is unaffected.
• The POST body accepts width and height as JSON integers. height may also be null to explicitly request auto-compute (the same as omitting it in the GET query string).

Related

• Projections — how width/height interact with auto projection fitting
• GET /map — full query-parameter reference
• POST /render/map — JSON body reference
• Response headers — caching, ETag, content-type