GET /map.{svg,png}

The GET endpoint turns query parameters into a static SVG or PNG map. Because the entire request is a URL, you can drop it straight into an <img> tag, a Markdown image, or an email. The response is permanently cached, so repeat loads are essentially free.

:::tip When to use GET vs POST Use GET when you have up to roughly 40 regions and your data fits comfortably in a URL (~2 KB). For larger datasets, structured JSON bodies, or CSV uploads, use POST /render/map instead. :::

Live example

https://api.maproll.io/map.png?scope=world&data=US:200,CN:150,IN:80,BR:60,RU:120,DE:95,FR:40,GB:55,JP:90&theme=dark&legendTitle=Sample

Query parameters

Param	Type	Default	Allowed values	Notes
scope	string	required	world, RO, …	See Scopes.
data	string	—	id:value[:#hex] pairs, comma-separated	Choropleth mode. See Data syntax below.
regions	string	—	id,id,… comma-separated	Highlight-only mode (no values). Cannot be combined with data.
theme	string	dark	dark light light-blue light-mono dark-blue dark-mono	See Themes.
format	string	derived from extension	svg png	Normally set by the URL path (.svg / .png).
width	integer	1200	1–8000	Output width in pixels.
height	integer	auto	1–8000	Output height in pixels. Omit to let the projection determine the aspect ratio.
projection	string	per-scope	naturalEarth1 albersUsa conicConformal mercator equalEarth	See Projections.
colorScale	string	sequential	sequential diverging categorical	See Color scales.
classification	string	quantile	quantile jenks equal custom	Binning method for sequential scales. Defaults to quantile. See Classification.
breaks	string	—	Comma-separated numbers, 1–20 values	Custom bin edges when classification=custom.
legend	boolean	true	true false 1 0	Show or hide the legend.
legendTitle	string	—	Max 64 chars	Label shown above the legend.
legendLayout	string	vertical	vertical horizontal continuous	See Legend.
title	string	—	Max 120 chars	Map title shown at the top. See Title & subtitle.
subtitle	string	—	Max 160 chars	Smaller text below the title.
attribution	boolean	true	true false 1 0	Shows "© OpenStreetMap contributors". Disable only if your embed context has its own attribution.
logo	boolean	false	true false 1 0	Shows the maproll wordmark. See Attribution & logo.
northArrow	boolean	false	true false 1 0	Renders a north arrow. See Overlays.
scaleBar	boolean	false	true false 1 0	Renders a scale bar.
graticule	boolean	false	true false 1 0	Renders latitude/longitude grid lines.
markers	string	—	See format below	Point markers with optional icon, label, and position. See Markers.
patterns	string	—	id:pattern,…	Per-region fill patterns. See Patterns.
annotations	string	—	id:text,…	Per-region tooltip text. See Annotations.
routes	string	—	See format below	Great-circle arcs between pairs of points or ISO codes. See Routes.
labels	string	—	ISO or id,id,…	Region labels on the map. ISO labels all polygons. See Region labels.
labelMinArea	number	—	0–1000000	Minimum polygon area (SVG units²) below which labels are suppressed.
proportional	string	—	Same id:value[:#hex] syntax as data	Sized circles at region centroids. See Proportional symbols.
proportionalMax	number	—	0–200	Maximum circle radius in pixels.
proportionalMin	number	—	0–100	Minimum circle radius in pixels.

Data syntax

The data parameter encodes choropleth values as a comma-separated list of pairs:

data=id:value
data=id:value:#rrggbb

• id — canonical region identifier (ISO 3166-1 alpha-2 for countries, ISO 3166-2 for sub-national regions).
• value — numeric value. May be negative or decimal.
• #rrggbb — optional 6-digit hex color that overrides the scale-derived fill for this region. See Color overrides.

Examples:

# Three countries, sequential ramp
data=US:200,CN:150,DE:95

# With per-region color override
data=US:200,CN:150,DE:95:%23ff0000

# Romanian counties
data=RO-B:500,RO-CJ:200,RO-IS:150

The # character must be URL-encoded as %23 in query strings.

The markers parameter uses semicolons to separate markers (because each marker already uses colons internally):

markers=lat,lon[:icon][:label][:labelPosition]

The routes parameter also uses semicolons:

routes=from>to[:#rrggbb][:width][:solid|dashed][:arrow]

Where from and to are either ISO codes (e.g. US) or lat,lon literals (e.g. 44.43,26.10).

Response

See Response headers & caching.

Related

• POST /render/map — for large datasets and structured payloads
• Response headers & caching
• Errors
• Scopes
• Themes