Markers

Markers overlay point symbols on top of any map — choropleth, highlight-only, or blank land. Pick from 30 built-in icons, add an optional label, and control label placement and size via the URL. Color and rotation require the JSON body (POST /render/map).

Icon gallery

All 30 icons at default size, placed in a grid across the world map:

https://api.maproll.io/map.png?scope=world&theme=light&width=1500&markers=70,-150:dot:dot:bottom%3B70,-90:square:square:bottom%3B70,-30:triangle:triangle:bottom%3B70,30:cross:cross:bottom%3B70,90:star:star:bottom%3B70,150:pin:pin:bottom%3B40,-150:flag:flag:bottom%3B40,-90:airport:airport:bottom%3B40,-30:anchor:anchor:bottom%3B40,30:car:car:bottom%3B40,90:bicycle:bicycle:bottom%3B40,150:helicopter:helicopter:bottom%3B10,-150:ship:ship:bottom%3B10,-90:train:train:bottom%3B10,-30:truck:truck:bottom%3B10,30:house:house:bottom%3B10,90:building:building:bottom%3B10,150:factory:factory:bottom%3B-20,-150:hospital:hospital:bottom%3B-20,-90:tank:tank:bottom%3B-20,-30:base:base:bottom%3B-20,30:bomb:bomb:bottom%3B-20,90:fist:fist:bottom%3B-20,150:soccer-ball:soccer-ball:bottom%3B-50,-150:megaphone:megaphone:bottom%3B-50,-90:mountain:mountain:bottom%3B-50,-30:fire:fire:bottom%3B-50,30:lightning:lightning:bottom%3B-50,90:warning:warning:bottom%3B-50,150:person:person:bottom

Icon library

Group	Icons
Generic shapes	dot, square, triangle, cross, star
Location	pin, flag
Transport	airport, anchor, car, bicycle, helicopter, ship, train, truck
Buildings	house, building, factory, hospital
Military / conflict	tank, base, bomb
Civic / activity	fist, soccer-ball, megaphone
Nature / hazard	mountain, fire, lightning, warning
Social	person

Examples

Five markers with different icons and label positions:

https://api.maproll.io/map.svg?scope=world&theme=dark&markers=44.43,26.10:pin:Bucharest%3B52.52,13.40:airport:Berlin%3B38.90,-77.04:flag:Washington:left%3B-33.87,151.21:anchor:Sydney:bottom%3B35.68,139.69:star:Tokyo:top

Markers over a choropleth — icons draw on top of the fill layer:

https://api.maproll.io/map.svg?scope=world&data=DE:100,RO:80,US:200,AU:50,JP:90&theme=light&markers=44.43,26.10:pin:Bucharest%3B52.52,13.40:airport:Berlin

Parameters

Param	Type	Default	Allowed	Notes
markers	string	—	See URL syntax below	Semicolon-separated list of marker definitions
icon	string	dot	Any of the 30 icon names	URL-encoded as part of the marker token
label	string	—	Up to 64 chars	Optional text drawn next to the icon. The 64-char cap is enforced on the JSON body; the URL parser does not truncate
labelPosition	string	right	top, bottom, left, right	Which side of the icon the label appears on
size	number	17	1–200 (px)	Fifth field of the URL marker token, or size in the JSON body
color	string	theme text color	6-digit hex #rrggbb	JSON body only — not available in the URL
rotation	number	0	-360–360 (degrees)	JSON body only — not available in the URL

URL syntax

markers=lat,lon[:icon][:label][:labelPosition][:size];lat,lon[:icon][:label][:labelPosition][:size];...

Field order within a token: lat,lon, then optionally icon, then label, then labelPosition, then size. Omit any trailing field you don't need.

# Minimal: just a dot at a coordinate
markers=44.43,26.10

# Icon + label
markers=44.43,26.10:pin:Bucharest

# Icon + label + position
markers=44.43,26.10:pin:Bucharest:top

# Icon + label + position + size (5th field, 1–200 px)
markers=44.43,26.10:pin:Bucharest:right:28

# Multiple markers (semicolon-separated; encode ; as %3B in a URL)
markers=44.43,26.10:pin:Bucharest%3B52.52,13.40:airport:Berlin

Two markers at different sizes — 28 px and 10 px:

https://api.maproll.io/map.svg?scope=world&theme=dark&markers=44.43,26.10:pin:Bucharest:right:28%3B52.52,13.40:airport:Berlin:right:10

JSON body syntax

Use POST /render/map with markers: MarkerInput[] for per-marker color and rotation:

{
  "scope": "world",
  "theme": "dark",
  "markers": [
    { "lat": 44.43, "lon": 26.10, "icon": "pin", "label": "Bucharest", "color": "#ff0000", "size": 20 },
    { "lat": 52.52, "lon": 13.40, "icon": "airport", "label": "Berlin", "color": "#00ff00", "rotation": 45 }
  ]
}

Notes

• color and rotation are JSON-only. size is available in both forms; per-marker color and rotation require the POST endpoint.
• Off-screen markers are silently skipped. Points outside the projection's visible domain (e.g. clipped by the projection boundary) produce no output rather than an error.
• Limit: 1000 markers per render. Exceeding it returns 400 too_many_markers on the URL path, and a schema error (Array must contain at most 1000 element(s)) on POST. The separate invalid_markers code covers malformed marker syntax in the URL, not the count cap.
• Detailed icons at small sizes. Icons like car, helicopter, bicycle, and hospital lose distinguishing features below ~10 px. Prefer dot, square, triangle, star, or pin for dense sets where each marker is small.
• Anchor, bicycle, and fist render as stroke (outline), not fill. All other icons are fill-based.
• soccer-ball, hospital, and warning use fill-rule="evenodd" so inner subpaths cut holes (the medical cross, the warning !).
• Each marker has a native <title> tooltip. Hovering in a browser shows the label text (or coordinates if no label).

Related

• Routes — draw great-circle paths between points; pairs naturally with endpoint markers
• Annotations — add hover tooltip text to regions (not markers)
• GET /map.{svg,png} — full query parameter reference
• POST /render/map — JSON body schema for per-marker color and rotation