Skip to main content

Classification

Classification controls how numeric values are divided into the color steps of a sequential scale. The four strategies produce visibly different maps from the same data — choosing the right one matters for your story.

Classification applies to sequential scales only. diverging and categorical scales have their own math and ignore this setting.

Examples​

The four renders below use identical data so you can compare directly.

Quantile (default)​

Each color step contains roughly the same number of regions. Good default — distributes color evenly across the map regardless of data skew.

https://api.maproll.io/map.svg?scope=world&theme=light&data=US:200,CN:150,RU:120,BR:60,IN:80,DE:95,FR:40,GB:55,JP:90,CA:30,MX:10,ZA:5&classification=quantile&legendTitle=Quantile
Quantile classification

Equal-interval​

Divides the [min, max] range into equal-width slices. Best when the underlying scale is uniform and you want absolute magnitudes to be readable from the legend.

https://api.maproll.io/map.svg?scope=world&theme=light&data=US:200,CN:150,RU:120,BR:60,IN:80,DE:95,FR:40,GB:55,JP:90,CA:30,MX:10,ZA:5&classification=equal&legendTitle=Equal-interval
Equal-interval classification

Jenks (natural breaks)​

Fisher-Jenks algorithm finds the break points that minimize within-class variance — it surfaces real clusters in the data. Legend stops fall at actual data gaps, not at regular intervals.

https://api.maproll.io/map.svg?scope=world&theme=light&data=US:200,CN:150,RU:120,BR:60,IN:80,DE:95,FR:40,GB:55,JP:90,CA:30,MX:10,ZA:5&classification=jenks&legendTitle=Jenks
Jenks natural-breaks classification

Custom breaks​

You specify the upper edge of each bin. The legend reads exactly the values you provide, making it easy to align with domain-specific thresholds (income brackets, risk tiers, etc.).

https://api.maproll.io/map.svg?scope=world&theme=light&data=US:200,CN:150,RU:120,BR:60,IN:80,DE:95,FR:40&classification=custom&breaks=10,30,60,100,150,200,300&legendTitle=Custom
Custom breaks classification

Parameters​

ParamTypeDefaultAllowedNotes
classificationstringquantilequantile, jenks, equal, customGET query param or JSON body field. Only affects sequential scales.
breaksstring / array—1–20 comma-separated numbers (GET) or a number array (POST)Required when classification=custom. Unsorted input is sorted automatically.

Notes​

  • quantile is stable across data updates — a new outlier doesn't reshuffle existing bins the way jenks can.
  • jenks can shift significantly when data changes between renders. Avoid it in dashboards where frame-to-frame consistency matters.
  • equal often concentrates most regions in the first bin when data is heavily skewed. Check the legend to see if this is happening.
  • custom break values are upper bounds — breaks=10,30,60 means "bin 1 ≤ 10, bin 2 ≤ 30, bin 3 ≤ 60". Values above the last break land in the highest color.
  • If you provide fewer custom breaks than ramp stops, the last break is repeated to fill the remainder. If you provide more, the list is truncated.
  • breaks has no effect unless classification=custom.

POST example​

curl -X POST 'https://api.maproll.io/render/map' \
  -H 'content-type: application/json' \
  -d '{
    "scope": "world",
    "theme": "light",
    "regions": [
      { "id": "US", "value": 200 },
      { "id": "CN", "value": 150 },
      { "id": "RU", "value": 120 }
    ],
    "classification": "custom",
    "breaks": [10, 30, 60, 100, 150, 200, 300]
  }'
  • Color Scales — sequential / diverging / categorical modes
  • Legend — how break points appear in the legend