Scopes list

A scope defines the geographic area and feature layer rendered by maproll. Every request must specify a scope via the scope parameter. The available scopes are loaded from the geo asset manifest at server boot, and the live list is also served at /healthz as scopes.

There are three scope families:

• world — every country polygon.
• Group scopes — named multi-country sets that alias the world topology and filter to their members.
• Country scopes — one per country with sub-national subdivisions (regions, counties, states).

At a glance

Family	Count	Layer	Default projection	Default detail level
World	1	countries	naturalEarth1	low
Group scopes	16	countries (filtered)	naturalEarth1	low
Country scopes	177	regions	conicConformal (albersUsa for US)	medium

Detail levels exist at low / medium / high. The server picks the level automatically; there is no URL override.

World

Scope ID	Layer	Default projection
world	countries	naturalEarth1

Group scopes

Group scopes alias the world topology and filter features to their member ISO 3166-1 alpha-2 codes. The projection fits the group's bounding box. All group scope IDs are uppercase.

Group ID	Label	Members	Default projection
EU	European Union (27)	AT, BE, BG, CY, CZ, DE, DK, EE, ES, FI, FR, GR, HR, HU, IE, IT, LT, LU, LV, MT, NL, PL, PT, RO, SE, SI, SK	naturalEarth1
NATO	NATO (32)	AL, BE, BG, CA, CZ, DE, DK, EE, ES, FI, FR, GB, GR, HR, HU, IS, IT, LT, LU, LV, ME, MK, NL, NO, PL, PT, RO, SE, SI, SK, TR, US	naturalEarth1
EUROPE	Europe (47)	AD, AL, AT, BA, BE, BG, BY, CH, CY, CZ, DE, DK, EE, ES, FI, FR, GB, GR, HR, HU, IE, IS, IT, LI, LT, LU, LV, MC, MD, ME, MK, MT, NL, NO, PL, PT, RO, RS, RU, SE, SI, SK, SM, TR, UA, VA, XK	naturalEarth1
AFRICA	Africa (53)	AO, BF, BI, BJ, BW, CD, CF, CG, CI, CM, CV, DJ, DZ, EG, ER, ET, GA, GH, GM, GN, GQ, GW, KE, KM, LR, LS, LY, MA, MG, ML, MR, MU, MW, MZ, NA, NE, NG, RW, SD, SL, SN, SO, SS, ST, SZ, TD, TG, TN, TZ, UG, ZA, ZM, ZW	naturalEarth1
ASIA	Asia (47)	AF, AM, AZ, BD, BH, BN, BT, CN, CY, GE, ID, IL, IN, IQ, IR, JO, JP, KG, KH, KP, KR, KW, KZ, LA, LB, LK, MM, MN, MV, MY, NP, OM, PH, PK, QA, SA, SG, SY, TH, TJ, TL, TM, TR, TW, UZ, VN, YE	naturalEarth1
APAC	Asia-Pacific (28)	AU, BD, BN, FJ, ID, IN, JP, KH, KP, KR, LA, MM, MN, MY, NP, NZ, PG, PH, PW, SB, SG, TH, TK, TL, TO, TV, VU, WS	naturalEarth1
N_AMERICA	North America (35)	AG, AI, AW, BB, BL, BM, BS, BZ, CA, CU, DM, DO, GD, GP, GT, HN, HT, JM, KN, LC, MF, MQ, MS, MX, NI, PA, PM, PR, SV, TC, TT, US, VC, VG, VI	naturalEarth1
S_AMERICA	South America (12)	AR, BO, BR, CL, CO, EC, GY, PE, PY, SR, UY, VE	naturalEarth1
OCEANIA	Oceania (14)	AU, FJ, FM, KI, MH, NR, NZ, PG, PW, SB, TO, TV, VU, WS	naturalEarth1
G7	G7 (7)	CA, DE, FR, GB, IT, JP, US	naturalEarth1
G20	G20 (19)	AR, AU, BR, CA, CN, DE, FR, GB, ID, IN, IT, JP, KR, MX, RU, SA, TR, US, ZA	naturalEarth1
BRICS	BRICS (9)	AE, BR, CN, EG, ET, IN, IR, RU, ZA	naturalEarth1
ASEAN	ASEAN (10)	BN, ID, KH, LA, MM, MY, PH, SG, TH, VN	naturalEarth1
ARAB_LEAGUE	Arab League (22)	AE, BH, DJ, DZ, EG, IQ, JO, KM, KW, LB, LY, MA, MR, OM, PS, QA, SA, SD, SO, SY, TN, YE	naturalEarth1
COMMONWEALTH	Commonwealth (51)	AG, AU, BB, BD, BN, BW, BZ, CA, CM, CY, DM, FJ, GB, GD, GH, GM, GY, IN, JM, KE, KI, KN, LC, LK, LR, LS, MT, MU, MV, MW, MY, MZ, NA, NG, NR, NZ, PG, PK, RW, SB, SZ, TO, TT, TV, TZ, UG, VC, VU, WS, ZA, ZM	naturalEarth1
SAHEL	Sahel (9)	BF, CF, CM, GN, ML, MR, NE, SN, TD	naturalEarth1

note

Membership counts above reflect the canonical group definitions. Some members may not have a country polygon shipped in the world topology (very small or disputed territories) — those are skipped at render time and reported as unknown ids in X-Geo-Warnings rather than failing the request.

Country scopes

Country scopes render the country's internal subdivisions. Inner IDs follow ISO 3166-2 (e.g. RO-B, RO-CJ). 177 country scopes ship today:

AD · AE · AF · AG · AM · AO · AR · AT · AU · AZ · BA · BB · BD · BE · BF · BG · BH · BI · BJ · BN · BO · BR · BS · BT · BW · BY · BZ · CA · CF · CG · CH · CI · CL · CM · CN · CO · CR · CU · CV · CY · DE · DJ · DK · DM · DO · DZ · EC · EE · EG · ER · ES · ET · FI · FJ · FM · FR · GA · GB · GE · GH · GL · GM · GN · GQ · GR · GT · GW · GY · HN · HR · HT · HU · ID · IE · IL · IN · IQ · IR · IS · IT · JO · JP · KE · KG · KH · KM · KN · KP · KR · KW · KZ · LA · LB · LC · LK · LR · LS · LT · LU · LY · MA · MC · MD · ME · ML · MM · MN · MR · MU · MV · MX · MY · MZ · NA · NE · NG · NI · NL · NO · NR · NZ · OM · PA · PE · PG · PH · PK · PL · PT · PW · PY · QA · RO · RS · RU · RW · SA · SB · SD · SE · SG · SI · SK · SL · SM · SN · SO · SR · SS · SV · SY · SZ · TD · TG · TH · TJ · TL · TM · TN · TO · TR · TT · TV · TW · TZ · UA · UG · US · UY · UZ · VC · VE · VU · YE · ZA · ZM · ZW

:::note Sub-national feature density varies Some country scopes ship with high-detail regions (large administrative divisions like provinces or states); others are sparse where OSM only publishes a single national outline. Country scopes always render a fitted projection over the country's bounding box; the inner-feature count depends on the source data. :::

Detail levels

• low — optimised for small embeds and thumbnails. Fewest vertices; smallest file transferred per request. World and group scopes default here.
• medium — general-purpose. Good balance of quality and file size for most use cases. Country scopes default here.
• high — maximum detail. Best for large print outputs or zoomed insets. Not used by default to keep render cost bounded.

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

Verifying live scopes

The set of scopes currently loaded by the server is exposed at:

GET https://api.maproll.io/healthz

The response is a JSON object whose scopes field is the sorted list of accepted scope IDs. Treat that as the source of truth; this document is regenerated when the manifest changes.

Adding new scopes

Scopes are not self-service today. Adding a new geography requires:

1. Sourcing OSM-exported GeoJSON for the country / region and dropping it into downloads/regions/<ISO-code>/ (countries) or extending src/geo/groups.ts (group scopes).
2. Running the build pipeline (npm run build:geo) to produce low / medium / high TopoJSON assets.
3. Redeploying the API so the manifest is reloaded at boot.

Related

• Scopes — conceptual overview and examples
• Projections — full list of supported projections and when to use each
• GET /map.{svg,png} — scope query parameter
• POST /render/map — scope in the JSON body