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). Accepted alongside data, but silently ignored when data is present — data takes over region fill entirely. Use one or the other.
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	—	Any string	Label shown above the legend. The 64-char cap applies to POST bodies only; GET does not enforce a length limit.
legendLayout	string	vertical	vertical horizontal continuous	See Legend.
title	string	—	Any string	Map title shown at the top. The 120-char cap applies to POST bodies only. See Title & subtitle.
subtitle	string	—	Any string	Smaller text below the title. The 160-char cap applies to POST bodies only.
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	—	Greater than 0, up to 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.
regionStroke	string	theme default	#rrggbb	Outline colour for every region. Applied to the whole regions group — per-region strokes are not supported.
regionStrokeWidth	number	theme default	0–20	Outline width in SVG units.
regionFill	string	—	none	The only accepted value. Forces every region's fill to none for an outline-only render.

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][:size]

size is an integer pixel size, 1–200. In place of a named icon, a 20- or 30-digit APP-6 / MIL-STD-2525 SIDC is also accepted. An unrecognised icon name does not fail the request — the marker renders a fallback glyph and the name is reported in the X-Geo-Warnings response header.

The routes parameter also uses semicolons:

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

Where from and to are either ISO codes (e.g. US) or lat,lon literals (e.g. 44.43,26.10). The optional fields after to are identified by their shape rather than their position, so they may appear in any order: #rrggbb is the colour, a 1–2 digit number is the width (1–20), solid/dashed is the style, arrow adds an arrowhead, and sea routes along sea lanes instead of a great circle.

Response

See Response headers & caching.

Related

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