Skip to main content

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

World choropleth — dark theme

Query parameters​

ParamTypeDefaultAllowed valuesNotes
scopestringrequiredworld, RO, …See Scopes.
datastring—id:value[:#hex], id:#hex, or id:label pairs, comma-separatedFour pair shapes; see Data syntax below. Numeric and string values cannot mix.
regionsstring—id,id,… comma-separatedHighlight-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.
themestringdarkdark light light-blue light-mono dark-blue dark-monoSee Themes.
formatstringderived from extensionsvg pngNormally set by the URL path (.svg / .png).
widthinteger12001–8000Output width in pixels.
heightintegerauto1–8000Output height in pixels. Omit to let the projection determine the aspect ratio.
projectionstringper-scopenaturalEarth1 albersUsa conicConformal mercator equalEarthSee Projections.
colorScalestringsequentialsequential diverging categoricalSee Color scales.
classificationstringquantilequantile jenks equal customBinning method for sequential scales. Defaults to quantile. See Classification.
breaksstring—Comma-separated numbers, 1–20 valuesCustom bin edges when classification=custom.
legendbooleantruetrue false 1 0Show or hide the legend.
legendTitlestring—Any stringLabel shown above the legend. The 64-char cap applies to POST bodies only; GET does not enforce a length limit.
legendLayoutstringverticalvertical horizontal continuousSee Legend.
titlestring—Any stringMap title shown at the top. The 120-char cap applies to POST bodies only. See Title & subtitle.
subtitlestring—Any stringSmaller text below the title. The 160-char cap applies to POST bodies only.
attributionbooleantruetrue false 1 0Shows "© OpenStreetMap contributors". Disable only if your embed context has its own attribution.
logobooleanfalsetrue false 1 0Shows the maproll wordmark. See Attribution & logo.
northArrowbooleanfalsetrue false 1 0Renders a north arrow. See Overlays.
scaleBarbooleanfalsetrue false 1 0Renders a scale bar.
graticulebooleanfalsetrue false 1 0Renders latitude/longitude grid lines.
markersstring—See format belowPoint markers with optional icon, label, and position. See Markers.
patternsstring—id:pattern,…Per-region fill patterns. See Patterns.
annotationsstring—id:text,…Per-region tooltip text. See Annotations.
routesstring—See format belowGreat-circle arcs between pairs of points or ISO codes. See Routes.
labelsstring—ISO or id,id,…Region labels on the map. ISO labels all polygons. See Region labels.
labelMinAreanumber—0–1000000Minimum polygon area (SVG units²) below which labels are suppressed.
labelTextstringcodecode nameNeeds labels. name draws English country names instead of codes. See Country-name labels.
proportionalstring—Same id:value[:#hex] syntax as dataSized circles at region centroids. See Proportional symbols.
proportionalMaxnumber—Greater than 0, up to 200Maximum circle radius in pixels.
proportionalMinnumber—0–100Minimum circle radius in pixels.
bboxstring—minLon,minLat,maxLon,maxLatCrops the projection viewport to a geographic rectangle. See Size & format → Viewport crop.
regionStrokestringtheme default#rrggbbOutline colour for every region. Applied to the whole regions group — per-region strokes are not supported.
regionStrokeWidthnumbertheme default0–20Outline width in SVG units.
regionFillstring—noneThe only accepted value. Forces every region's fill to none for an outline-only render.
detailstringlow on world and group scopes, medium otherwiselow medium highGeometry detail level. Use medium for sharp coastlines on a zoomed bbox crop of the world. See Detail level.
disputedstring—ID,… or allWorld and group scopes only. Hatches disputed and occupied areas over the data colours. See Disputed areas.
disputedStylestringhatchhatch bwNeeds disputed. bw fills each area opaque black and white with its own pattern. See Black-and-white disputed areas.
bordersstring—A-B,…, up to 50 pairsHighlights the shared border of each pair of region IDs. See Highlighted borders.
borderColorstringtheme text colour#rgb #rrggbbColour of the borders lines. URL-encode # as %23.
borderWidthnumber2.50.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
IDAreaControlled byClaimed by
CRIMEACrimeaRussiaUkraine
WESTERN-SAHARAWestern SaharaMoroccothe Sahrawi Republic
GOLANGolan HeightsIsraelSyria
NORTHERN-CYPRUSNorthern Cyprusthe Turkish Cypriot administration (Turkish-backed)Cyprus
SOUTH-OSSETIASouth OssetiaRussian-backed de facto authoritiesGeorgia
ABKHAZIAAbkhaziaRussian-backed de facto authoritiesGeorgia
TRANSNISTRIATransnistriaRussian-backed de facto authoritiesMoldova
KURILS-SOUTHSouthern Kuril IslandsRussiaJapan
KASHMIR-PKGilgit-Baltistan and Azad KashmirPakistanIndia
KASHMIR-INJammu and Kashmir and LadakhIndiaPakistan
AKSAI-CHINAksai ChinChinaIndia
SHAKSGAMTrans-Karakoram TractChinaIndia
  • IDs are case-insensitive. Both sides of Kashmir are listed, so all treats 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=all leaves out Abkhazia and South Ossetia.
  • Country scopes reject disputed=. scope=IN already draws the areas India claims (Pakistani-administered Kashmir, Aksai Chin, Shaksgam) hatched under its states, and scope=PK draws 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.

PatternAreas
Vertical stripesKASHMIR-PK, ABKHAZIA, KURILS-SOUTH
DotsKASHMIR-IN
CheckerAKSAI-CHIN, SHAKSGAM, CRIMEA, GOLAN, NORTHERN-CYPRUS
Diagonal stripesTRANSNISTRIA, WESTERN-SAHARA
Reverse diagonal stripesSOUTH-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:

  1. The country-scope disputed under-layer (scope=IN only)
  2. Regions
  3. The disputed overlay
  4. Highlighted borders
  5. Custom shapes
  6. Routes
  7. Labels
  8. 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​

CodeCause
invalid_disputeddisputed= on a country scope, or an unknown ID (even alongside all, as in all,NOPE).
invalid_bordersA 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_borderColorNot #rgb or #rrggbb.
invalid_borderWidthNot a number.
invalid_detailNot low, medium or high.
invalid_disputedStyleNot hatch or bw, or given without disputed.
invalid_labelTextNot code or name, or given without labels.

All of them return 400. See Errors.

Response​

See Response headers & caching.