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.

On the GET endpoint the extension sets the default format, and an explicit format= parameter overrides it in either direction: /map.svg?format=png returns image/png, and /map.png?format=svg returns image/svg+xml. Normally you just pick the matching extension. 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 ~450 KB.	Scales with pixel count. A 1200 px wide world PNG is typically ~150 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.

Viewport crop (bbox)

By default a render shows the full bounds of the scope — scope=world shows the whole globe, scope=RO shows all of Romania. Pass bbox=minLon,minLat,maxLon,maxLat to refit the projection to an arbitrary geographic rectangle:

?scope=world&bbox=53.5,25.5,59.5,27.5    # Strait of Hormuz
?scope=world&bbox=5,43,30,58             # European Union
?scope=world&bbox=-77.5,38.7,-76.7,39.1  # Washington DC + suburbs
?scope=RO&bbox=25.5,44,27.5,45.5         # SE corner of Romania

The projection refits to the bbox; features that fall outside the rectangle are clipped automatically. Choropleth fills, markers, routes, shapes, and labels all still render normally — only the viewport changes.

Constraints:

• minLon, maxLon ∈ [-180, 180]; minLat, maxLat ∈ [-90, 90]
• minLon < maxLon and minLat < maxLat
• Antimeridian-spanning bboxes (e.g. 170,-10,-170,10) are not supported in v1; split into two renders

Cache: bbox is part of the cache key, so two different bboxes against the same data produce two cache entries. Re-using the same URL is free.

JSON body: pass as a tuple — "bbox": [53.5, 25.5, 59.5, 27.5].

Aspect ratio interaction: when height is omitted, the auto-height pass uses the bbox geometry (not the scope's full bounds), so the canvas height reflects the cropped region — a tall narrow bbox produces a tall narrow canvas at the requested width.

File-size guidance

Measured against the live API at width=1200 unless noted:

Scenario	SVG size	PNG size
world (229 features, low detail)	~455 KB	~151 KB
world at width 300 (thumbnail)	~424 KB	~27 KB
world at width 2400 (presentation)	~476 KB	~340 KB
Group scope EU	~37 KB	~87 KB
Group scope NATO	~106 KB	~48 KB
Country scope RO (42 subdivisions, medium)	~431 KB	~144 KB
Country scope US (51 subdivisions, medium)	~14.8 MB	~154 KB

Two things to take from this table:

• SVG size tracks geometry, not pixels. The same world map is ~424 KB at 300 px and ~476 KB at 2400 px — the small variation is coordinate precision, not resolution. PNG size, by contrast, scales with pixel area.
• Some country scopes are very large as SVG. OSM-derived subdivision geometry at medium detail is dense, and US in particular is ~14.8 MB of SVG. When embedding a detailed country scope in a browser page or an email, request PNG — the same map rasterises to ~154 KB.

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