Overlays
Three independent cartographic overlays add professional polish to any map. All three default to off — opt in to whichever you need. They work on any scope and projection.
| Overlay | Toggle | Position |
|---|---|---|
| North arrow | northArrow=true | Top-right |
| Scale bar | scaleBar=true | Bottom-left |
| Graticule | graticule=true | Under regions (ocean only) |
Examples
All three overlays on one map:
https://api.maproll.io/map.svg?scope=world&theme=light&data=US:200,CN:150,DE:95,FR:40,BR:60&northArrow=true&scaleBar=true&graticule=true
North arrow only:
https://api.maproll.io/map.svg?scope=world&theme=dark&data=US:1&northArrow=true
Scale bar only:
https://api.maproll.io/map.svg?scope=world&theme=dark&data=US:1&scaleBar=true
Graticule only — 10° lat/lon grid visible in the oceans:
https://api.maproll.io/map.svg?scope=world&theme=dark&data=US:1&graticule=true
Parameters
| Param | Type | Default | Allowed | Notes |
|---|---|---|---|---|
northArrow | boolean | false | true, false, 1 | Compass + "N" label, top-right corner |
scaleBar | boolean | false | true, false, 1 | Kilometre scale bar, bottom-left |
graticule | boolean | false | true, false, 1 | 10° lat/lon grid under regions |
All three are independent — combine any subset.
JSON body syntax
{
"scope": "world",
"theme": "light",
"regions": [{ "id": "US", "value": 1 }],
"northArrow": true,
"scaleBar": true,
"graticule": true
}
Notes
- All three default off. Existing renders are unaffected unless you add a toggle.
- Graticule renders under regions. The 10° grid is drawn between the background and the region fills, so it is only visible in ocean areas and continental gaps. This is standard cartographic convention.
- Scale bar uses kilometres. The displayed distance is auto-rounded to a "nice" value (1/2/5 × 10ⁿ km) near a 140-pixel target bar width. The exact number depends on the projection's scale at the map center.
- Scale bar accuracy degrades on world projections. Equal-area and compromise projections (Natural Earth, Equal Earth) change scale across the map. The scale bar samples the center of the image and is most accurate near the equator. For regional scopes (
RO, country-level) the bar is more reliable. - North arrow is fixed north-up. All supported projections render north-up; rotating the glyph per-projection would mislead more than help.
- When the scale bar and attribution are both visible, the attribution text shifts upward so they don't overlap — the same stacking behavior as the legend and logo.
- No position, size, or color overrides in v1. Overlays use fixed corners and dimensions (north arrow 36×36 px, scale bar target 140 px). No miles or nautical miles option.
- Graticule density is fixed at 10°. There is no parameter to change the grid spacing.
Related
- Region labels — text labels on polygon faces
- Branding: title and subtitle — top-of-map text
- Branding: attribution and logo — bottom corner branding elements
GET /map.{svg,png}— full query parameter reference