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. There are three families:

• world — every country polygon, ISO 3166-1 alpha-2 keyed.
• Country scopes — one per ISO 3166-1 alpha-2 code with shipped regional data (RO, US, FR, …). Renders the country's internal subdivisions (counties, states, regions). IDs are ISO 3166-2.
• Group scopes — named multi-country sets that alias the world topology and filter to their members (EU, NATO, G7, AFRICA, …). IDs inside are ISO 3166-1 alpha-2.

The full enumerated list lives in Scopes list.

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

EU group scope — choropleth limited to member states

https://api.maproll.io/map.svg?scope=EU&data=DE:80,FR:70,IT:60,ES:50,PL:40,RO:30&theme=light-blue&legendTitle=Sample

NATO group scope — highlight without values

https://api.maproll.io/map.svg?scope=NATO&theme=dark

Parameters

Param	Type	Default	Allowed	Notes
scope	string	—	See Scopes list	Required. Case-sensitive. Returns 404 if unrecognised.

ID conventions

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

Scope family	Inner-feature ID format	Example
world	ISO 3166-1 alpha-2	US, DE, RO
Country scopes (RO, US, …)	ISO 3166-2	RO-B, RO-CJ, US-CA
Group scopes (EU, NATO, …)	ISO 3166-1 alpha-2 (filtered to members)	DE, FR, RO

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 and group scopes default to low (they alias the world topology — same simplification budget).
• All country scopes default to medium (sub-country features need finer geometry to read).

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

Default projection per scope family

• world, group scopes → naturalEarth1
• US → albersUsa
• All other country scopes → conicConformal, with parallels derived from the scope's bounding box

Override the default by passing the projection query parameter — see Projections.

Group scopes — what they do

A group scope aliases the world topology and filters features to its member ISO codes. Practically:

• The projection fits the group's bounding box, not the whole world.
• data=DE:80,FR:70 works the same way as on world, but countries outside the group don't render.
• Group scope IDs are uppercase (EU, NATO, G7, BRICS, ASEAN, AFRICA, EUROPE, ASIA, APAC, N_AMERICA, S_AMERICA, OCEANIA, G20, ARAB_LEAGUE, COMMONWEALTH, SAHEL).

See Scopes list for the full membership of each group.

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 including every country scope and every group scope with members
• 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