Skip to main content

Region labels

Region labels draw the canonical ISO identifier (e.g. US, RO-B) as text at the visual center of each polygon. Two modes: label every polygon, or label an explicit list of regions. Both modes drop polygons below labelMinArea. A greedy collision algorithm places larger polygons first and skips smaller ones whose label would overlap.

Examples​

All countries labelled in ISO mode (large countries get labels; small island nations are skipped):

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&labels=ISO
World choropleth with ISO labels

Romania counties — all 42 labelled by setting a low labelMinArea:

https://api.maproll.io/map.svg?scope=RO&theme=light&data=RO-B:500,RO-CJ:200,RO-IS:150,RO-TM:180&labels=ISO&labelMinArea=20
Romania counties with labels

Only a specific list of countries:

https://api.maproll.io/map.svg?scope=world&theme=light&data=US:1&labels=RO,DE,FR,IT,ES
Only specified countries labelled

High labelMinArea — only the very largest countries get labels:

https://api.maproll.io/map.svg?scope=world&theme=light&data=US:1&labels=ISO&labelMinArea=10000
Only largest countries labelled

Parameters​

ParamTypeDefaultAllowedNotes
labelsstring—ISO or comma-separated idsISO considers every polygon; a list considers only those ids. Both then apply labelMinArea
labelMinAreanumber2000–1,000,000 (screen px²)Applies in both modes — a named id whose polygon is smaller than this still gets no label

URL syntax​

# ISO mode — label every polygon above the default or specified area threshold
labels=ISO

# Explicit list — consider only these ids (still subject to labelMinArea)
labels=RO,DE,FR,IT,ES

# ISO mode with a custom area threshold
labels=ISO&labelMinArea=500

JSON body syntax​

{
  "scope": "world",
  "theme": "light",
  "regions": [{ "id": "US", "value": 1 }],
  "labels": "ISO",
  "labelMinArea": 100
}

For an explicit list:

{
  "scope": "world",
  "theme": "light",
  "labels": ["RO", "DE", "FR"]
}

Notes​

  • ISO is a keyword, not an id. The string "ISO" triggers auto-labelling mode. Any other value (including a single id like labels=RO) is treated as an explicit id list.
  • Explicit id lists still honour labelMinArea. Naming a region selects it as a candidate; the area filter then runs exactly as it does in ISO mode. labels=RO,DE,FR,IT,ES&labelMinArea=500000 draws nothing at all. If a small named region isn't appearing, lower labelMinArea.
  • Collision avoidance is greedy by descending screen area. Bigger polygons place first; smaller polygons yield when their label bbox would overlap an already-placed label. No backtracking — a polygon skipped due to collision will not be retried.
  • Labels display the feature id, not a human-readable name. For countries this is the ISO 3166-1 alpha-2 code (DE, US); for subnational regions it's the ISO 3166-2 code (RO-B, US-CA).
  • Placement uses the screen-space polygon centroid. For most convex country shapes this falls inside the polygon. For crescent or island-chain shapes it may sit in the ocean — a known limitation in v1.
  • Text has a halo. A background-colored stroke behind each label keeps it readable over any choropleth fill.
  • labelMinArea=0 will attempt to label every polygon in the topology, including tiny islands — this can produce a very dense or unreadable result on a world map.
  • Invalid labelMinArea (non-numeric or outside 0–1,000,000) returns 400 invalid_labelMinArea.