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. It is defined only over US territory, so applying it to another scope silently drops every feature that falls outside that area — scope=world&projection=albersUsa renders a handful of paths on an otherwise empty canvas rather than a world map.

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, and the projection is additionally rotated to put the bounding box's mid-longitude on the central meridian. Without that rotation the cone's axis would sit at 0° longitude and any scope offset from Greenwich (Romania at ~25°E, say) would render visibly tilted. Both are automatic; there is no URL parameter to override the parallels or the rotation directly.
• When a bbox is supplied, the parallels and rotation are derived from the bbox rather than the scope's full bounds.
• 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