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

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 id:value pairs. Optional third field: id:value:#hex for a per-region color override. Semicolons also accepted as separators.
regionsstring—Comma-separated IDs with no values — highlight mode. 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.
valuenumbernoFinite number. Omit to use highlight mode for that entry.
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.
  • Values must be finite numbers. NaN, Infinity, and null are rejected (or treated as highlight-only for null in the JSON body).
  • IDs are case-insensitive — ro, RO, and Ro all resolve to the same region.
  • data= color override syntax: the third colon-delimited field must be URL-encoded — # becomes %23. Example: RO:120:%23ff0000.
  • 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.