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

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

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

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

Parameters

Param	Type	Default	Allowed	Notes
classification	string	quantile	quantile, jenks, equal, custom	GET query param or JSON body field. Only affects sequential scales.
breaks	string / array	—	1–20 comma-separated numbers (GET) or a number array (POST)	Needed for classification=custom to do anything — omitting it falls back to quantile rather than erroring. 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.
• Fewer custom breaks than ramp stops gives you exactly the bins you asked for. breaks=10,100 produces a two-stop legend reading 10, 100 — not a seven-stop one padded with repeats. The two colors are sampled across the whole ramp, so the scale still runs lightest to darkest.
• More custom breaks than ramp stops are sorted, then truncated to the first 7. breaks=1,2,3,4,5,6,7,8,9,10,11,12 yields the bins 1…7; everything above 7 falls into the top color.
• breaks has no effect unless classification=custom. With classification=custom and no breaks, the scale silently falls back to quantile.

Bin count and duplicate edges

The number of bins is the ramp length — 7 — and is not configurable; there is no bins parameter.

After the chosen strategy computes its bin edges, edges that repeat are collapsed, and this applies to all four strategies. A classification cannot have more classes than the data has distinct values: asking for 7 quantile bins from 5 numbers makes several edges land on the same value, and the legend would otherwise repeat itself (12, 12, 9.9, 5.8, 5.8). So the stop count you actually get is the number of distinct edges, up to 7:

Input	Legend stops
7 values, quantile	6 (one duplicate edge collapsed)
7 values, equal or jenks	7
3 values, any strategy	3
classification=custom&breaks=10,100,300	3

The surviving colors are sampled evenly across the full ramp rather than sliced off one end, so a three-bin map still runs from the lightest stop to the darkest.

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]
  }'

Related

• Color Scales — sequential / diverging / categorical modes
• Legend — how break points appear in the legend