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",
  "breaks": [],
  "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.

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.
  • 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.