Skip to main content

POST /render/map

The POST endpoint accepts either a JSON body (application/json) or a CSV body (text/csv) and returns an SVG or PNG map. Use POST when your data has more than ~40 regions, when you need to pass structured nested objects (markers, routes, annotations), or when you are uploading a CSV file directly from a script or pipeline.

Content types​

Send the full request as a JSON body. All rendering parameters and data live in the body — no query string needed.

Body schema:

{
  "scope": "world",
  "regions": [
    { "id": "RO", "value": 120 },
    { "id": "DE", "value": 95, "color": "#1a6bcc" },
    { "id": "FR", "value": 40, "pattern": "stripes" },
    { "id": "US", "value": 200, "annotation": "Largest economy" }
  ],
  "theme": "dark",
  "format": "png",
  "width": 1200,
  "height": null,
  "projection": "naturalEarth1",
  "colorScale": "sequential",
  "classification": "quantile",
  "legend": true,
  "legendTitle": "GDP rank",
  "legendLayout": "vertical",
  "title": "World GDP",
  "subtitle": "2024 estimates",
  "attribution": true,
  "logo": false,
  "northArrow": false,
  "scaleBar": false,
  "graticule": false,
  "labels": "ISO",
  "labelMinArea": 5000,
  "proportional": [
    { "id": "US", "value": 200, "color": "#ff6600" }
  ],
  "proportionalMax": 40,
  "proportionalMin": 4,
  "markers": [
    {
      "lat": 44.43,
      "lon": 26.10,
      "icon": "pin",
      "label": "Bucharest",
      "labelPosition": "right",
      "color": "#ff0000",
      "size": 16,
      "rotation": 0
    }
  ],
  "routes": [
    {
      "from": "RO",
      "to": "DE",
      "color": "#ffffff",
      "width": 2,
      "style": "dashed",
      "arrow": true
    }
  ]
}

All fields except scope are optional.

Field reference:

FieldTypeDefaultNotes
scopestringrequiredSee Scopes.
regionsarray—Up to 5000 items. Each item: id (required), value (number → choropleth, string up to 64 chars → categorical bucket, or null for highlight-only), color (#rrggbb), pattern, annotation. Numeric and string values cannot mix in one request.
themestringdarkdark light light-blue light-mono dark-blue dark-mono
formatstringsvgsvg or png
widthinteger12001–8000 pixels
heightinteger or nullnull1–8000 pixels. null = auto (projection aspect ratio).
projectionstringper-scopenaturalEarth1 albersUsa conicConformal mercator equalEarth
colorScalestringsequentialsequential diverging categorical
classificationstringquantilequantile jenks equal custom
breaksnumber[]—Custom bin edges (1–20 values). Used when classification is custom.
legendbooleantrue
legendTitlestring—Max 64 chars
legendLayoutstringverticalvertical horizontal continuous
titlestring—Max 120 chars
subtitlestring—Max 160 chars
attributionbooleantrue
logobooleanfalse
northArrowbooleanfalse
scaleBarbooleanfalse
graticulebooleanfalse
labels"ISO" or string[]—"ISO" labels all polygons; array labels specific IDs.
labelMinAreanumber—0–1000000 SVG units². Suppresses labels on small polygons.
proportionalarray—Sized circles. Each item: id, value, optional color.
proportionalMaxnumber—Max circle radius in pixels (0–200).
proportionalMinnumber—Min circle radius in pixels (0–100).
markersarray—Up to 1000 items. Each: lat, lon, optional icon or sidc (mutually exclusive), size, color, rotation, label, labelPosition. sidc is a 20- or 30-digit APP-6 / MIL-STD-2525 code — see Military symbols.
routesarray—Up to 500 items. Each: from, to, optional fromLatLon, toLatLon, color, width (1–20), style, arrow, mode (great-circle | sea).
shapesFeatureCollection—Up to 500 features. User-supplied GeoJSON overlay (Point / LineString / MultiLineString / Polygon / MultiPolygon). Per-feature style via properties (fill / stroke / strokeWidth / opacity / dashArray / radius / title). See Custom shapes.
bboxnumber[]—[minLon, minLat, maxLon, maxLat]. Crops the projection viewport. minLon must be less than maxLon (no antimeridian span) and minLat less than maxLat.
regionStrokestringtheme default#rrggbb outline colour for every region. Applied to the whole regions group — per-region strokes are not supported.
regionStrokeWidthnumbertheme defaultOutline width, 0–20.
regionFillstring—"none" is the only accepted value. Forces every region's fill to none for an outline-only render.

curl example:

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},
      {"id": "US", "value": 200}
    ],
    "theme": "dark",
    "format": "png",
    "legendTitle": "GDP rank"
  }' \
  --output map.png

Categorical-by-label example: pass text labels for regions[].value and set colorScale to categorical (the GET endpoint auto-selects this; on POST it's explicit). Each distinct label gets its own color from the theme's categorical palette; the legend names the buckets.

curl -X POST https://api.maproll.io/render/map \
  -H 'Content-Type: application/json' \
  -d '{
    "scope": "world",
    "colorScale": "categorical",
    "regions": [
      {"id": "US", "value": "NATO"}, {"id": "GB", "value": "NATO"},
      {"id": "FR", "value": "NATO"}, {"id": "DE", "value": "NATO"},
      {"id": "CN", "value": "BRICS"}, {"id": "RU", "value": "BRICS"},
      {"id": "IN", "value": "BRICS"}, {"id": "BR", "value": "BRICS"}
    ],
    "theme": "dark",
    "legendTitle": "Bloc"
  }' \
  --output map.svg

Limits​

  • Maximum body size: 4 MB on api.maproll.io (4,194,304 bytes). The renderer and the reverse proxy in front of the public endpoint share that ceiling; a larger body is rejected by the proxy with a 413 before it reaches the app.
  • Maximum regions per request: 5000.
  • Maximum markers per request: 1000.
  • Maximum routes per request: 500.
  • Maximum custom shape features per request: 500.

Response​

See Response headers & caching.