Projections

A projection defines how the sphere of the Earth is flattened onto the map canvas. Different projections make different tradeoffs between shape accuracy, area accuracy, and visual familiarity. maproll picks a sensible default per scope, but you can override it.

All five projections come from d3-geo. The height is auto-derived from the projection's natural aspect ratio when you omit the height parameter.

Examples

All examples use the same world scope so the deformation differences are visible.

naturalEarth1 — world default, balanced compromise

https://api.maproll.io/map.svg?scope=world&data=US:1,RU:1,CA:1&theme=light-blue&projection=naturalEarth1

equalEarth — honest country sizes

https://api.maproll.io/map.svg?scope=world&data=US:1,RU:1,CA:1&theme=light-blue&projection=equalEarth

mercator — shape-preserving, extreme pole distortion

https://api.maproll.io/map.svg?scope=world&data=US:1,RU:1,CA:1&theme=light-blue&projection=mercator

conicConformal — regional default with auto-parallels

https://api.maproll.io/map.svg?scope=RO&data=RO-B:500,RO-CJ:200,RO-IS:150,RO-TM:180&theme=light&projection=conicConformal

Parameters

Param	Type	Default	Allowed	Notes
projection	string	scope-dependent	naturalEarth1, albersUsa, conicConformal, mercator, equalEarth	Case-sensitive. Returns 400 if unrecognised.

Scope defaults

Scope	Default projection	Why
world	naturalEarth1	A compromise projection — neither conformal nor equal-area but familiar and visually balanced at world scale
US	albersUsa	Albers USA insets Alaska and Hawaii into a standard continental frame, which is the expected layout for US state-level data
All other scopes	conicConformal	Parallels are derived automatically from the feature collection's bounding box, giving a sensible fit for any country or region

When to pick which

naturalEarth1 — the best all-around world projection. Shapes are recognisable and the polar regions are not heavily distorted. Use it as your world default unless you have a specific reason to switch.

equalEarth — an equal-area world projection. Africa, North America, and Antarctica appear in their true relative sizes. Use it when accurately communicating country size or density matters (population maps, emissions per km²).

mercator — a conformal projection: shapes are locally accurate, but areas are severely exaggerated toward the poles. Greenland and Russia appear much larger than they are. Use it when you are zooming into a small area where local shape accuracy matters more than world context.

conicConformal — the automatic default for any non-world scope. Parallels are derived from the latitude extent of the feature collection, so you do not need to configure anything. Shapes are accurate for mid-latitude regions. Appropriate for any single country or subnational scope.

albersUsa — the standard US layout, with Alaska and Hawaii repositioned as insets below the lower-48. Only useful with the US scope (or if you manually pass US state data to world).

Notes

• When height is omitted, the server fits the projection to the requested width first, then computes the height from the projected bounding box. This is a two-pass operation and produces exact aspect-ratio-correct output without rounding error.
• For conicConformal, parallels are set to [midLat − span/3, midLat + span/3] derived from the feature collection's bounding box. This is automatic; there is no URL parameter to override the parallels directly.
• Passing an unknown projection name returns 400 with {"error":"invalid_projection", ...}.

Related

• Scopes — each scope has a default projection
• Size and format — how width/height interact with auto-fitting
• GET /map — full query-parameter reference