Proportional Symbols

Proportional symbols draw a circle at each region's centroid, sized so that visual area is proportional to value (square-root scaling). They let you encode two variables on one map: choropleth color for one dimension, circle size for another.

Examples

Dual-encoding — choropleth color + circle size

Color encodes one variable (GDP-like), circle area encodes another (population-like). China and India have the largest circles; France and Germany the smallest.

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&proportional=US:330,CN:1400,RU:145,BR:215,IN:1400,DE:84,FR:68

Proportional only (no choropleth)

Omit data= to show circles on a plain land-color base.

https://api.maproll.io/map.svg?scope=world&theme=dark&proportional=US:330,CN:1400,IN:1400,RU:145,BR:215,JP:125,DE:84

Per-circle color override

Each circle can carry its own hex color. Circles without a color use the theme's highlight color.

https://api.maproll.io/map.svg?scope=world&theme=light&proportional=US:100:%23ff0000,CN:200:%2300ff00,RU:50

Custom size range

proportionalMax sets the radius of the largest circle; proportionalMin sets the floor for tiny values.

https://api.maproll.io/map.svg?scope=world&theme=light&proportional=US:100,CN:400&proportionalMax=80&proportionalMin=10

Parameters

Param	Type	Default	Allowed	Notes
proportional	string / array	—	GET: id:value[:%23hex],... — same grammar as data=. POST: [{ id, value, color? }].	Comma-separated pairs. # must be URL-encoded as %23 in GET.
proportionalMax	number	40	1–200	Radius in pixels of the circle for the largest value.
proportionalMin	number	4	0–100	Minimum radius in pixels. Applied when sqrt(v/vmax) * proportionalMax would be smaller.

Sizing math

radius = max(proportionalMin, sqrt(value / max_value) * proportionalMax)

The largest value gets exactly proportionalMax radius. All others scale by the square root of their ratio, preserving the correct area-to-value relationship. Values at or below zero receive proportionalMin.

Notes

• Area, not radius, is proportional to value. Square-root scaling (Bertin / Flannery) is the cartographic standard for circle symbols.
• Max 5,000 entries, shared with the regions array limit.
• Render order: large circles draw first so smaller ones appear on top — smaller circles are harder to see when occluded.
• Circle opacity is 0.7 so the underlying choropleth fill remains visible through the symbol.
• Circles have a 1-px stroke in the theme background color for crispness against any fill.
• There is no proportional legend in v1. The legend shows the choropleth scale only.
• No collision detection — dense regions (Europe) will overlap. Filter down to fewer regions if overlap is a problem.

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 }
    ],
    "proportional": [
      { "id": "US", "value": 330, "color": "#ff0000" },
      { "id": "CN", "value": 1400 }
    ]
  }'

Related

• Data Input — data= syntax that proportional= reuses
• Color Overrides — per-region hex fills on the choropleth layer
• Dual-encoding recipe — step-by-step guide to combining choropleth + circles
• Themes — the highlight color used when no per-circle color is specified