Skip to main content

Dual encoding — color and size

A single choropleth can show one variable. When you need to show two — say, GDP per capita (a rate) alongside total population (a magnitude) — you can layer proportional circles on top of the choropleth. Color communicates the rate; circle area communicates the count or magnitude. The two encodings are visually independent, so readers can compare across both dimensions at once.

What you'll build​

A world map where the choropleth fill represents GDP per capita (darker = higher) and the circle size represents population (bigger = more people). China and India dominate the circles; smaller wealthy nations appear as small circles on a dark fill.

World map with choropleth fills and proportional circles

Steps​

  1. Prepare your two datasets. Each region needs an entry in data= (the choropleth value) and, separately, an entry in proportional= (the circle size value). The two lists do not need to be the same length — a region can appear in one but not the other.

    data=US:200,CN:150,RU:120,BR:60,IN:80,DE:95,FR:40,GB:55,JP:90,CA:30
    proportional=US:330,CN:1400,RU:145,BR:215,IN:1400,DE:84,FR:68,GB:67,JP:125,CA:38

  2. Add legendTitle so readers know what the color scale represents. There is no separate legend for the circles in v1 — label your map with a title or subtitle to explain both dimensions.

    title=GDP+per+capita+vs+Population&theme=light&legendTitle=GDP+index

  3. Assemble the final URL.

    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&proportional=US:330,CN:1400,RU:145,BR:215,IN:1400,DE:84,FR:68,GB:67,JP:125,CA:38&legendTitle=GDP+index&title=GDP+per+capita+vs+Population
    GDP per capita vs population — dual encoding

  4. Tune circle sizes with proportionalMax (the radius of the largest circle, in pixels) and proportionalMin (the floor radius for the smallest). The defaults are proportionalMax=40 and proportionalMin=4.

    proportionalMax=50&proportionalMin=6

Variations​

  • Circles only, no choropleth. Omit data= entirely. All regions render in the theme's default land color; only the circles carry data:

    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. Append :#rrggbb to any proportional= entry to give that circle a specific color. Useful for categorical groupings:

    proportional=US:100:%231d4ed8,CN:200:%23dc2626,DE:50

    See Color overrides for the hex format.

  • Use a diverging scale for the choropleth. Pairs well with circles when the color represents a rate of change:

    https://api.maproll.io/map.svg?scope=world&theme=light&colorScale=diverging&data=US:5,CA:-3,MX:1,CN:8,RU:-5&proportional=US:330,CN:1400,RU:145

    See Color scales for sequential vs diverging.

  • POST body for dynamic data. Pass both arrays in a single JSON body — useful when you generate the data server-side:

    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": "IN", "value": 80 }
        ],
        "proportional": [
          { "id": "US", "value": 330 },
          { "id": "CN", "value": 1400 },
          { "id": "IN", "value": 1400 }
        ],
        "legendTitle": "GDP index"
      }'
  • Proportional symbols — sizing math, per-circle color, proportionalMax/proportionalMin
  • Color scales — sequential, diverging, categorical ramps for the choropleth layer
  • Classification — bin strategy for the choropleth (quantile, Jenks, equal interval, custom)
  • Themes — how the default circle color (theme.highlight) varies per theme