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], id:#hex, or id:label pairs, comma-separated	Four pair shapes; see Data syntax below. Numeric and string values cannot mix.
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.
bbox	string	—	minLon,minLat,maxLon,maxLat	Crops the projection viewport to a geographic rectangle. See Size & format → Viewport crop.

Data syntax

The data parameter encodes one of four per-pair shapes. The renderer picks the meaning from the shape of each pair — there's no per-parameter mode switch.

data=id:value              # numeric choropleth value
data=id:value:#rrggbb      # numeric value + per-region color override
data=id:#rrggbb            # color-only paint (no value, no scale binning)
data=id:label              # text label → categorical bucket (auto-categorical)

• id — canonical region identifier (ISO 3166-1 alpha-2 for countries, ISO 3166-2 for sub-national regions). Case-insensitive.
• value — finite number. May be negative or decimal.
• #rrggbb — 6-digit hex color. As the second field (id:#hex) it paints the region directly; as the third (id:value:#hex) it overrides the scale just for that region. See Color overrides.
• label — non-empty string, max 64 chars, no embedded #. Each distinct label gets a distinct color from the theme's categorical palette; the legend names the buckets. See Color scales → Categorical.

Mix freely except across numeric ↔ string values. Color-only pairs (id:#hex) coexist with either kind, but a request that mixes US:200 and CN:NATO is rejected with 400 mixed_data_types.

Examples:

# Sequential ramp on three countries
data=US:200,CN:150,DE:95

# One region pinned red, others follow the scale
data=US:200,CN:150,DE:95:%23ff0000

# Paint three countries directly, no scale, no legend
data=US:%23dc2626,CN:%232563eb,DE:%2316a34a   # + legend=false

# Two qualitative buckets — auto-selects colorScale=categorical
data=US:NATO,GB:NATO,CN:BRICS,RU:BRICS

# 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