Projections
Starting from v2.6, Mapbox GL JS supports multiple map projections. This feature allows you to create more accurate visualizations at every zoom level and tell a better story with your data.
In the latest Mapbox styles, Globe is the default projection. (Streets, Outdoors, and Satellite Streets v12 and Light/Dark v11)In Navigation, Satellite, and earlier style versions the default is Mercator.
Map Projections
A map projection is a way to flatten the planet's surface onto a page or screen. Every projection has strengths and weaknesses, so the right projection depends on your use case.
For most maps, we recommend using globe to accurately represent locations on the Earth. The most notable limitation of globe is that only half the earth is visible onscreen at once. If you're building a static map or data visualization, an alternative projection might be a good choice.
Mapbox GL JS provides a variety of alternative "adaptive" projections, including projections optimized for thematic world maps, and projections for representing specific regions (such as the contiguous U.S. or Europe).
Use projections in Mapbox GL JS
Projections are compatible with all tile sources and most map styles (with a few caveats below). See this example to get started quickly, or explore all available projections in this more advanced example.
You can set the projection by editing the map style in Mapbox Studio, with the map constructor’s projection
option, or at runtime via the setProjection
method. Mapbox v12 styles include the Globe projection by default. Maps with no projection set default to the Mercator projection.
What projections are available?
Developers can select any of the following options when defining a style (each projection is defined in more detail below):
- Globe: A 3D representation of the Earth.
globe
, the default in v12 styles
- Thematic: Curved map edges create a pleasing aesthetic suggesting classic world maps. A good choice for world-scale thematic maps.
- Equal-area: Relative size of regions is accurate, but shapes are distorted. -
equalEarth
- Compromise: A balance of shape and size distortion. -naturalEarth
-winkelTripel
- Equal-area: Relative size of regions is accurate, but shapes are distorted. -
- Conic: Distortion is minimized in one area. A good choice for maps limited to a specific country or region.
- Equal-area: Relative area is accurate, but shapes are distorted.
- Conformal: Shapes and angles are accurate, but sizes are distorted.
- Rectangular: These projections can loop across the 180th Meridian, useful for viewing the Pacific ocean. Known as cylindrical projections in cartography.
- Compromise: A balance of shape and size distortion.
- Conformal: Shapes and angles are accurate, but sizes are distorted.
mercator
, the default if not set in style
Define a projection as a Map constructor option
You can define a map projection when creating a Map
instance using shorthand:
const map = new mapboxgl.Map({
container: 'map',
projection: 'naturalEarth'
});
Set a projection at runtime
You can set or change the map’s projection after Map
creation by using the setProjection
method:
// Use shorthand with default parameters
map.setProjection('equalEarth');
// Or override the projection-specific options
map.setProjection({
name: 'albers',
center: [41.33, 123.45],
parallels: [30, 50]
});
Define a projection in a style
You can define a projection in a map style:
const map = new mapboxgl.Map({
style: {
version: 8,
name: 'My Projected Style',
sources: {
// ...
},
layers: [
// ...
],
projection: {
name: 'equalEarth'
}
}
});
Important notes about using projections in a style:
- A projection defined in a style must be an object. The string shorthand is not valid in a style specification.
- If you define one projection in a style, and set a different one at runtime (either through the map’s constructor or
setProjection
), then the runtime projection will be used. - Calling
map.setProjection(null)
will revert from any runtime projection to the one defined in the style.
Get current map projection
Developers can get the current map’s projection using map.getProjection()
.
Adaptive Projection Behavior
Map “unskewing” on zoom
Adaptive projections in Mapbox GL JS (all projections besides globe and Mercator) have a novel adaptive design that adjusts the projection as you zoom in to reduce distortion at all zoom levels by gradually transitioning from the defined projection to Web Mercator (which is optimal on higher zooms).
Zoom and bearing
For any camera zoom level and location, maps in adaptive projections will be rendered at the same scale they would be rendered in Mercator.
The bearing in rectangular projections corresponds directly to the rotation of the map (north is up). In thematic and conic projections, the concept of bearing is more complicated since the direction of north can be different at different points on the map:
- At low zoom levels, the bearing corresponds to the direction of north at the center of the projection.
- At high zoom levels, the bearing corresponds to the direction of north at the center of the screen.
- At intermediate zoom levels, bearing transitions between the two meanings.
Constraining interaction
Maximum bounds constraints work differently with adaptive projections. Map panning and zooming is constrained in a way so that the center of the map doesn’t go beyond the specified geographic bounds, rather than the whole visible area. We may revisit this behavior in a future release.
Limitations of Adaptive Projections
Adaptive projections don't support all features supported by Globe and Mercator. We plan to add support for these features in a future release.
3D and Background styling
3D terrain and Free Camera API can only be used with Globe and Mercator.
Atmospheric styling is also supported only in globe and Mercator projections. In other projections, the empty area around the world is always rendered as transparent and can be styled by changing the CSS background property on the map container.
Custom style layers
CustomLayerInterface
can only be used only with Mercator.
Thematic Projections
In these following three projections, curved map edges create a pleasant rounded aesthetic suggesting classic world maps. These projections are good choices for data visualization on a global scale.
Equal Earth and Natural Earth are Pseudocylindrical projections, with straight lines of latitude and curved lines of longitude. Winkel Tripel is a Pseudoazimuthal projection with lines of latitude bending slightly inward.
Equal Earth
The Equal Earth projection (defined as equalEarth
in the Mapbox GL JS API) is a pseudocylindrical, equal-area projection. This projection accurately reflects sizes and is thus especially useful in data visualization when it's important to make regional size comparisons.
A notable use of Equal Earth projection is thematic maps on global temperature anomalies by NASA.
Natural Earth
The Natural Earth projection (defined as naturalEarth
in the Mapbox GL JS API) is a pseudocylindrical, compromise projection. This projection looks much like Equal Earth but displays a more "natural" appearance by minimizing shape distortion at the cost of a small amount of size distortion.
Winkel Tripel
The Winkel Tripel projection (defined as winkelTripel
in the Mapbox GL JS API) is a “modified azimuthal” compromise projection. The “tripel” part of the name comes from its goal of minimizing distortion in three aspects: area, direction and distance.
Winkel Tripel appears taller and more rounded than Equal Earth and Natural Earth, and provides more accurate shapes with less accurate sizes. Winkel Tripel is commonly regarded as one of the least distorted compromise projections. The National Geographic Society and many other educational institutions use Winkel Tripel for global thematic mapping.
The curved latitude lines in Winkel Tripel make it unsuitable for maps where comparing latitude is important.
Conic Projections
Conic projections create a map with little distortion in the area around a specific point. Further away from this point, distortion increases. In albers
, this is shape distortion, while in lambertConformalConic
size increases with greater distance.
This area can be placed anywhere on the earth as described below.
Albers
The Albers projection (defined as albers
in the Mapbox GL JS API) is a conic, equal-area projection. Like Equal Earth, this projection provides accurate relative sizes, but shapes are increasingly distorted at further distances.
By default, the Albers projection is centered on the mainland United States at [-96, 37.5]
with the standard parallels [29.5, 45.5]
. This “Albers USA” projection is commonly used for showing geographic data in which comparing state-level sizes is important, for example in U.S. elections. Notable users of the projection include U.S. Geographical Survey, U.S. Census Bureau, and National Atlas of the U.S.
Composite Albers projection (for example where Alaska and Hawaii are alongside the mainland U.S.) is not yet supported in Mapbox GL JS.