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 above a minimum area, or label an explicit list of regions. 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 labels every polygon ≥ labelMinArea; a list labels only those ids
labelMinAreanumber2000–1,000,000 (screen px²)Only applies in ISO mode; explicit id lists always label regardless of area

URL syntax​

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

# Explicit list — always label these ids, no area check
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 ignore labelMinArea. When you name a region explicitly, it is always labelled regardless of its screen size.
  • 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.