Scopes

A scope is a preloaded geography that the server renders. Every request must specify exactly one scope. The scope determines which features are drawn, which projection is used by default, and which IDs are valid in data=, regions=, and related parameters.

Scopes are built from OSM-derived GeoJSON at deploy time and loaded into memory at server boot. Adding a new scope is an operator task, not a self-service URL parameter.

Examples

World map — 229 country features, Natural Earth projection

https://api.maproll.io/map.svg?scope=world&data=US:200,CN:150,IN:80,BR:60,RU:120,DE:95,FR:40,GB:55,JP:90,CA:30&theme=dark&legendTitle=Sample

Romania — 42 județe, conic-conformal projection

https://api.maproll.io/map.svg?scope=RO&data=RO-B:500,RO-CJ:200,RO-IS:150,RO-TM:180,RO-BV:120,RO-CT:100&theme=light&legendTitle=Population

Romania highlight-only (no values)

https://api.maproll.io/map.svg?scope=RO&data=RO-B:1,RO-CJ:1,RO-TM:1,RO-IS:1&theme=dark

Parameters

Param	Type	Default	Allowed	Notes
scope	string	—	world, RO	Required. Case-sensitive. Returns 404 if unrecognised.

ID conventions

IDs follow international standards so they compose with external datasets without a mapping step.

Scope	ID format	Example
world	ISO 3166-1 alpha-2	US, DE, RO
RO	ISO 3166-2	RO-B, RO-CJ, RO-TM

IDs are matched case-insensitively at normalisation time and uppercased before lookup. Unknown IDs do not cause an error — they are silently skipped and reported in the X-Geo-Warnings response header (e.g. unknown-ids:XX,ZZ). See Response headers for details.

Detail levels

Each scope ships at three detail levels: low, medium, and high. The server selects the level automatically:

• world requests default to low to keep render times fast at the typical 1200 px width.
• All other scopes (RO, …) default to medium.

There is no URL parameter to override the detail level — the server picks the best level for the scope.

Currently shipping scopes

Scope	Features	Layer	Default projection
world	229 OSM-derived country polygons	countries	naturalEarth1
RO	42 județe (counties)	regions	conicConformal

For the full table including detail-level file sizes, see Scopes list.

Notes

• Requesting an unknown scope returns 404 with {"error":"invalid_scope", ...}.
• The world scope includes overseas territories and disputed regions as separate features wherever OSM carries them.
• Adding a custom scope requires the operator to drop GeoJSON files into downloads/regions/<name>/, run npm run build:geo, and restart the server. It is not a self-service feature in the current version.

Related

• Scopes list — full enumerated table of scopes, features, and sizes
• Projections — each scope has a default projection; you can override it
• GET /map — full query-parameter reference
• POST /render/map — JSON and CSV body reference