Projection

A style's projection property sets which projection a map is rendered in.

A map projection is a way to flatten the globe's surface onto a screen. While flattening, distortion is inevitable—some parts will stretch and some will squish. Nearly all web maps use the Mercator projection, which maintains angles and shapes and works well for high zoom levels. But Mercator distorts the size of regions on lower zoom levels, like when looking at data on a national or global overview map. For example, Greenland is visually the same size as Africa on a Mercator map, even though it is 14 times smaller in reality. Other projections can correct this distortion.

Mapbox GL supports different kinds of projections that preserve different qualities:

  • equal-area projections: the size of areas is preserved, but shapes are distorted
    • equalEarth
    • albers
  • conformal projections: shapes and angles are preserved, but sizes are distorted
    • mercator
    • lambertConformalConic
  • compromise projections: balances area and shape distortion
    • winkelTripel
    • naturalEarth
  • equidistant projections: Some distances are preserved
    • equirectangular

Some projections can be configured for different regions. Albers projection configured for Alaska:

"projection": {
  "name": "albers",
  "center": [
    -154,
    50
  ],
  "parallels": [
    55,
    65
  ]
}

name

Required enum. One of "albers", "equalEarth", "equirectangular", "lambertConformalConic", "mercator", "naturalEarth", "winkelTripel". Defaults to "mercator".

The name of the projection to be used for rendering the map.

"albers":

An Albers equal-area projection centered on the continental United States. You can configure the projection for a different region by setting center and parallels properties. You may want to set max bounds to constrain the map to the relevant region.

"equalEarth":

An Equal Earth projection.

"equirectangular":

An Equirectangular projection. This projection is very similar to the Plate Carrée projection.

"lambertConformalConic":

A Lambert conformal conic projection. You can configure the projection for a region by setting center and parallels properties. You may want to set max bounds to constrain the map to the relevant region.

"mercator":

The Mercator projection is the default projection.

"naturalEarth":

A Natural Earth projection.

"winkelTripel":

A Winkel Tripel projection.

SDK SupportMapbox GL JSAndroid SDKiOS SDKmacOS SDK

basic functionality

>= 2.6.0Not yet supportedNot yet supportedNot yet supported

center

Optional array of numbers. Requires name to be "albers", or "lambertConformalConic".

The reference longitude and latitude of the projection. center takes the form of [lng, lat]. This property is only configurable for conic projections (Albers and Lambert Conformal Conic). All other projections are centered on [0, 0].

"center": [
  -96,
  37.5
]
SDK SupportMapbox GL JSAndroid SDKiOS SDKmacOS SDK

basic functionality

>= 2.6.0Not yet supportedNot yet supportedNot yet supported

parallels

Optional array of numbers. Requires name to be "albers", or "lambertConformalConic".

The standard parallels of the projection, denoting the desired latitude range with minimal distortion. parallels takes the form of [lat0, lat1]. This property is only configurable for conic projections (Albers and Lambert Conformal Conic).

"parallels": [
  29.5,
  45.5
]
SDK SupportMapbox GL JSAndroid SDKiOS SDKmacOS SDK

basic functionality

>= 2.6.0Not yet supportedNot yet supportedNot yet supported