Skip to main content

Data Input

maproll accepts region data in three formats: a compact URL query string for quick embeds, a JSON array for programmatic use, and a CSV body for spreadsheet-style workflows. All three produce the same rendered output.

Examples​

GET — URL query string​

https://api.maproll.io/map.svg?scope=world&data=US:200,CN:150,IN:80,BR:60,RU:120,DE:95,FR:40&theme=dark&legendTitle=Sample
World choropleth via GET data= param

GET — highlight-only (no values)​

Use regions= when you want to fill countries a single accent color without driving a color scale.

https://api.maproll.io/map.svg?scope=world&regions=RO,DE,FR,IT,ES,PT,NL,BE&theme=light-mono
Highlight-only mode via regions= param

GET — color-only paint (no values)​

When the message is purely "paint these regions these colors" — brand-color highlights, a quick three-country comparison — use the id:#hex shape on data=. There's no scale, no value, and you'll typically pair it with legend=false.

https://api.maproll.io/map.svg?scope=world&data=US:%23dc2626,RU:%232563eb,DE:%2316a34a&theme=light&legend=false
Color-only paint — three countries, no scale

GET — categorical buckets by text label​

Pass non-numeric values to group regions into named buckets. The renderer auto-selects colorScale=categorical, picks distinct palette colors per label, and the legend names the buckets.

https://api.maproll.io/map.svg?scope=world&data=US:NATO,GB:NATO,FR:NATO,DE:NATO,CN:BRICS,RU:BRICS,IN:BRICS,BR:BRICS&theme=dark
Categorical-by-label — NATO vs BRICS, auto-categorical

POST — JSON body​

curl -X POST 'https://api.maproll.io/render/map' \
  -H 'content-type: application/json' \
  -d '{
    "scope": "world",
    "regions": [
      { "id": "RO", "value": 120 },
      { "id": "DE", "value": 95 },
      { "id": "FR", "value": 40 }
    ],
    "theme": "dark",
    "legendTitle": "GDP"
  }'

POST — CSV body​

Scope, theme, and other render options are passed as query params; the CSV body carries just the data.

printf 'id,value\nRO,120\nDE,95\nFR,40\n' | \
  curl -X POST 'https://api.maproll.io/render/map?scope=world&theme=light&format=svg' \
    -H 'content-type: text/csv' --data-binary @-

Parameters​

GET endpoint​

ParamTypeDefaultNotes
datastring—Comma-separated pairs. Four accepted shapes per pair: id:value (numeric → choropleth), id:value:#hex (numeric + per-pair color override), id:#hex (color-only paint, no value), id:label (text label → categorical bucket; auto-selects colorScale=categorical). Numeric and string values cannot mix in the same request.
regionsstring—Comma-separated IDs with no values — highlight mode. All listed IDs render in the theme's single accent color. Cannot be combined with data on the same request.

POST endpoint — regions array​

FieldTypeRequiredNotes
idstringyesRegion identifier (ISO 3166-1 alpha-2 for world scope; ISO 3166-2 for sub-country scopes). Max 16 characters. Uppercased automatically.
valuenumber | stringnoFinite number → choropleth value. String (max 64 chars) → categorical bucket label. Omit (or null) to use highlight mode for that entry. Numeric and string values cannot mix across the same regions array.
colorstringno6-digit hex, e.g. #ff0000. Overrides the scale-derived fill. See Color Overrides.
patternstringnoOne of stripes, stripes-diagonal, dots, crosshatch, solid-outline. See Patterns.
annotationstringnoFree-text string appended to the SVG <title> tooltip on hover. Max 200 characters.

POST endpoint — CSV body​

The CSV body must have an id column and optionally a value column. A color column (#rrggbb) and a pattern column are also honored when the header is present. Extra columns are ignored.

id,value,color
RO,120,#ff0000
DE,95,
FR,40,#00ff00

Notes​

  • Max 5,000 region entries per request across all three input methods.
  • Numeric values must be finite. NaN and Infinity are rejected. null is treated as highlight-only.
  • Categorical labels are non-empty strings up to 64 characters (no embedded # — that's reserved for hex colors). They feed colorScale=categorical, which auto-activates on the GET endpoint when you don't pass colorScale explicitly.
  • Mixing numeric and string values in one request returns a 400 mixed_data_types error — the scale either bins magnitudes or names buckets, never both. Color-only paint (id:#hex) is exempt and mixes freely with either kind.
  • IDs are case-insensitive — ro, RO, and Ro all resolve to the same region.
  • URL-encoding #: in data= query strings the # in #ff0000 must be %23. Examples: RO:120:%23ff0000 or US:%23dc2626.
  • When data= and regions= are both absent, the map renders all regions in the theme's base land color with no legend.
  • Unknown IDs are silently skipped; the response includes an X-Geo-Warnings: unknown-ids:XX,YY header listing them.