Skip to main content

Annotations

Annotations attach a short text note to any region's native browser tooltip. When a viewer hovers over a country or region in a browser, the OS tooltip shows the annotation alongside the region's value. No JavaScript, no popovers — the text lives in the SVG <title> element and works inside <img> tags too.

Examples​

Two annotated regions — hover in a browser to see the tooltips:

https://api.maproll.io/map.svg?scope=world&theme=dark&data=RO:120,DE:95&annotations=RO:Election+2024,DE:GDP+down+2%25
Map with region annotations

Annotation-only (no choropleth values) — tooltips provide context without filling regions:

https://api.maproll.io/map.svg?scope=world&theme=dark&annotations=US:Largest+economy,CN:Second+largest,DE:Largest+EU+economy
Map with annotation-only tooltips

Annotation containing a colon — the parser splits only on the first colon, so timestamps and source citations work:

https://api.maproll.io/map.svg?scope=world&theme=dark&data=RO:120&annotations=RO:Source%3A+WHO+2023
Map with annotation containing a colon

Parameters​

ParamTypeDefaultAllowedNotes
annotationsstring—See URL syntaxComma-separated id:text pairs
annotationstring—Up to 200 charsPer-region field in the JSON body (regions[].annotation)

URL syntax​

annotations=id:text,id:text,...

The first colon in each entry separates the region id from the text. Subsequent colons are part of the text, so annotations like RO:Source: WHO 2023 work correctly.

URL-encode spaces as + or %20, percent signs as %25, and colons within the text as %3A:

# Basic annotation
annotations=RO:Election+2024

# Multiple regions
annotations=RO:Election+2024,DE:GDP+down+2%25

# Annotation containing a colon
annotations=RO:Source%3A+WHO+2023

JSON body syntax​

Annotations are set per-region in the regions array:

{
  "scope": "world",
  "theme": "light",
  "regions": [
    { "id": "DE", "value": 95, "annotation": "G7 member" },
    { "id": "RO", "value": 120, "annotation": "EU member, NATO 2004" }
  ]
}

Tooltip format​

The SVG <title> content depends on what is present for the region:

Region hasTooltip shows
Value + annotationRO: 120 — Election 2024
Value onlyRO: 120
Annotation only (no value)RO — Source: WHO
NeitherRO

The separator between value and annotation is an em-dash (—). < and & in annotation text are automatically XML-escaped.

Notes​

  • Native browser tooltips only. The SVG <title> element surfaces as the OS-native hover label. This is the ceiling for tooltip behavior in static SVG — no custom styling, no popover positioning.
  • Tooltips work inside <img> tags in most browsers but not in all (some browsers suppress <title> tooltips on SVG served as an image). For guaranteed hover behavior, link to the SVG directly rather than embedding.
  • 200-character limit per annotation. Enough for a one-line context note; keeps <title> from becoming unwieldy in screen-reader output. Text beyond 200 characters is rejected with 400 invalid_annotations.
  • Annotations have no effect on the visual render. The map looks identical with or without annotations — they only affect the tooltip text.
  • No annotations on markers. Markers have their own label field and derive their tooltip from it. The annotations parameter keys on region ids, not marker positions.
  • No formatting. Plain text only — no bold, italics, or links inside the annotation.