Skip to main content

Legend

The legend explains the color ramp used in a choropleth map. It can be shown or hidden, given a custom heading, and rendered in one of three layouts depending on the map's shape and the nature of the data.

Examples​

Vertical (default) — stacked swatches

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&legendTitle=GDP&legendLayout=vertical
World choropleth with a vertical legend stacked in the bottom-right

Horizontal — swatches in a row

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&legendTitle=GDP&legendLayout=horizontal
World choropleth with a horizontal legend row at the bottom-right

Continuous — smooth gradient bar

https://api.maproll.io/map.svg?scope=world&theme=light&data=US:200,CN:150,RU:120,BR:60,IN:80&legendTitle=GDP&legendLayout=continuous
World choropleth with a continuous gradient legend bar and min/mid/max labels

Parameters​

ParamTypeDefaultAllowedNotes
legendbooleantruetrue / falseShow or hide the legend entirely.
legendTitlestring—Up to 64 characters in a JSON bodyHeading text above the legend. Omit for no heading. The 64-character cap is enforced on POST /render/map; the URL endpoint does not truncate or reject longer text, it just draws it.
legendLayoutstringverticalvertical / horizontal / continuousControls the visual shape of the legend.

Notes​

Vertical stacks swatch-and-label rows from bottom to top (low values at the bottom — the standard cartographic convention). Works for any number of bins and aspect ratio.

Horizontal arranges swatches left to right with labels underneath. A good choice for wide, banner-aspect maps where vertical real-estate is limited.

Continuous renders a single <linearGradient> bar with three labels: minimum (left), midpoint (centre), maximum (right). The midpoint label is omitted when fewer than three stops exist. This layout works best with sequential or diverging color scales where bin boundaries are not meaningful — it communicates "low to high" without implying discrete steps.

Continuous + categorical — using legendLayout=continuous with colorScale=categorical does not make sense semantically, and the renderer does not stop you. Layout is chosen on its own: you get a gradient bar that interpolates between the categorical colors, with only the first and last category labels (plus a middle one when there are three or more). Categories are not ordered, so that bar implies a progression that isn't there. Use vertical or horizontal for categorical data.

Legend position is fixed. All three layouts are anchored in the bottom-right corner. There is no position parameter. When logo=true, the legend is shifted up by the height of the wordmark band so the two stack rather than overlap; all three layouts respect that shift. Nothing else moves the legend — scaleBar=true, for example, shifts the attribution line but leaves the legend where it is.

The legend needs a value scale. It is drawn only when the map has values to bin — that is, a data= list with numeric or categorical values. Highlight-only maps (regions=…) and color-only paint maps (data=US:%23ff0000) render no legend at all, even with legend=true, because there is no scale to describe.