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. |
labelText | string | code | code name | Needs labels. name draws English country names instead of codes. See Country-name labels. |
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. |
detail | string | low on world and group scopes, medium otherwise | low medium high | Geometry detail level. Use medium for sharp coastlines on a zoomed bbox crop of the world. See Detail level. |
disputed | string | — | ID,… or all | World and group scopes only. Hatches disputed and occupied areas over the data colours. See Disputed areas. |
disputedStyle | string | hatch | hatch bw | Needs disputed. bw fills each area opaque black and white with its own pattern. See Black-and-white disputed areas. |
borders | string | — | A-B,…, up to 50 pairs | Highlights the shared border of each pair of region IDs. See Highlighted borders. |
borderColor | string | theme text colour | #rgb #rrggbb | Colour of the borders lines. URL-encode # as %23. |
borderWidth | number | 2.5 | 0.5–12 (clamped) | Width of the borders lines in pixels. Values outside the range are clamped, not rejected. |
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.
Disputed areas
disputed= draws a hatched overlay on top of the regions of a world or group scope. The stripes are transparent, so the fill of the country that controls the area (its data colour) still shows through, and each area gets a dashed outline. The attribution line reads "Hatched: disputed · © OpenStreetMap contributors".
disputed=CRIMEA,ABKHAZIA,SOUTH-OSSETIA
disputed=all
| ID | Area | Controlled by | Claimed by |
|---|---|---|---|
CRIMEA | Crimea | Russia | Ukraine |
WESTERN-SAHARA | Western Sahara | Morocco | the Sahrawi Republic |
GOLAN | Golan Heights | Israel | Syria |
NORTHERN-CYPRUS | Northern Cyprus | the Turkish Cypriot administration (Turkish-backed) | Cyprus |
SOUTH-OSSETIA | South Ossetia | Russian-backed de facto authorities | Georgia |
ABKHAZIA | Abkhazia | Russian-backed de facto authorities | Georgia |
TRANSNISTRIA | Transnistria | Russian-backed de facto authorities | Moldova |
KURILS-SOUTH | Southern Kuril Islands | Russia | Japan |
KASHMIR-PK | Gilgit-Baltistan and Azad Kashmir | Pakistan | India |
KASHMIR-IN | Jammu and Kashmir and Ladakh | India | Pakistan |
AKSAI-CHIN | Aksai Chin | China | India |
SHAKSGAM | Trans-Karakoram Tract | China | India |
- IDs are case-insensitive. Both sides of Kashmir are listed, so
alltreats neither side as settled. - Each area is cut from the country polygon it is drawn in on the world map, so its edge sits exactly on that country's edge.
- In the SVG, each area is a
<path class="disputed-area" data-id="CRIMEA">whose<title>names who controls the area and who claims it. - On a group scope, areas whose controlling country isn't a member are skipped silently. For example,
scope=EUROPE&disputed=allleaves out Abkhazia and South Ossetia. - Country scopes reject
disputed=.scope=INalready draws the areas India claims (Pakistani-administered Kashmir, Aksai Chin, Shaksgam) hatched under its states, andscope=PKdraws the area Pakistan claims (Indian-administered Jammu and Kashmir and Ladakh), without any parameter.
Black-and-white disputed areas
disputedStyle=bw replaces the transparent hatch with an opaque black-and-white fill, a different pattern for neighbouring areas, so the two sides of the Line of Control read apart on a close-up. The dashed outline stays. The marks are about 6 px wide on a 1400 px render and scale with width, whatever the bbox zoom.
| Pattern | Areas |
|---|---|
| Vertical stripes | KASHMIR-PK, ABKHAZIA, KURILS-SOUTH |
| Dots | KASHMIR-IN |
| Checker | AKSAI-CHIN, SHAKSGAM, CRIMEA, GOLAN, NORTHERN-CYPRUS |
| Diagonal stripes | TRANSNISTRIA, WESTERN-SAHARA |
| Reverse diagonal stripes | SOUTH-OSSETIA |
disputed=KASHMIR-PK,KASHMIR-IN,AKSAI-CHIN,SHAKSGAM&disputedStyle=bw
disputedStyle=hatch is the default and the same request as leaving it out.
Country-name labels
labelText=name makes labels= draw English country names (bold, about 18 px on a 1400 px render, with a dark halo) instead of ISO codes. Sub-national IDs keep their code. A few names follow house style: Palestine, DR Congo, Congo, United States, UK, North Korea, South Korea, Myanmar, Ivory Coast, Kosovo, Taiwan, Turkey, Central African Rep., South Sudan.
bbox=60,22,98,40&labels=PK,AF,IN,CN&labelText=name
Name labels are placed where the name has the most room inside the part of the country that is visible in the frame. On a bbox crop that cuts a country off, its label still lands on screen. A name never sits on a drawn disputed area or on another label, and a country with no visible spot gets no label. labelText=code is the default and the same request as leaving it out.
Highlighted borders
borders= draws the shared boundary of each pair of regions as a heavy line, exactly on the edge the regions layer draws.
borders=IN-PK,AF-PK&borderColor=%2322d3ee&borderWidth=4
borders=US-CA-US-NV
A pair is two region IDs joined by -. Sub-national IDs contain a hyphen of their own, so a pair is split into two equal halves: US-CA-US-NV is California and Nevada. In the SVG, each line is a <path data-border="IN-PK"> with a <title>.
Layer order
From bottom to top:
- The country-scope disputed under-layer (
scope=INonly) - Regions
- The disputed overlay
- Highlighted borders
- Custom shapes
- Routes
- Labels
- Markers
Detail level
World and group scopes render from the low detail geometry by default, and every other scope from medium. That suits a full-world map. On a zoomed bbox crop of the world, low coastlines look coarse, so pass detail=medium. Regions, borders and disputed areas all follow the chosen level, so they stay aligned.
detail=high is slower. A 1400×1000 South Asia crop takes about 0.6 s as PNG, and its SVG is about 7 MB, because a crop still carries the features outside the frame. For embeds, use medium, or request high as PNG.
Asking for a scope's default level (scope=world&detail=low) is the same request as leaving detail out, and it shares that request's cache entry.
Errors for these parameters
| Code | Cause |
|---|---|
invalid_disputed | disputed= on a country scope, or an unknown ID (even alongside all, as in all,NOPE). |
invalid_borders | A pair that can't be split in two, a region paired with itself (IN-IN), a pair listed twice or reversed in one list (IN-PK,PK-IN), more than 50 pairs, an ID that isn't in the scope or group, or a pair with no shared border (FR-JP). |
invalid_borderColor | Not #rgb or #rrggbb. |
invalid_borderWidth | Not a number. |
invalid_detail | Not low, medium or high. |
invalid_disputedStyle | Not hatch or bw, or given without disputed. |
invalid_labelText | Not code or name, or given without labels. |
All of them return 400. See Errors.
Response
See Response headers & caching.
Related
- POST /render/map — for large datasets and structured payloads
- Response headers & caching
- Errors
- Scopes
- Themes