> For the complete documentation index, see [llms.txt](https://docs.mapbox.com/android/maps/llms.txt)

# Projections

A [**map projection**](https://docs.mapbox.com/help/glossary/projection/) is a way of transforming the three-dimensional planet to a two-dimensional plane like 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.

The Maps SDK for Android supports the following projections:

-   [**Globe**](#globe) (`globe`): A 3D representation of the Earth.
-   [**Mercator**](#mercator) (`mercator`): Shapes and angles are accurate, but sizes are distorted.
-   [**Albers**](#albers) (`albers`): Relative area is accurate, but shapes are distorted. Available starting with v11.32.0.

Your browser doesn't support HTML5 video. Open [link to the video](https://docs.mapbox.com/android/android/assets/medias/maps-guides-projections-4ea851c71afbabefd8f1197f3cee8477.mp4).

> **Related content (guide): [Projections in Mapbox GL JS](https://docs.mapbox.com/mapbox-gl-js/guides/projections/)**
> 
> Learn more about map projections, including the projections available in Mapbox GL JS.

## Default projection

The map style sets the projection. If you don't overwrite it at runtime:

-   With the [Mapbox Standard](https://docs.mapbox.com/map-styles/standard/guides/) style, or a style that imports Standard and doesn't set its own projection, the map displays **Globe**.
-   With any other style that doesn't set a projection, the map displays **Mercator**.

## Set a projection in a style

You can set the projection by editing the [map style](https://docs.mapbox.com/style-spec/reference/root/#projection) in Mapbox Studio, or in a style JSON that you load at runtime:

```json
{
  "version": 8,
  "projection": { "name": "albers" },
  "imports": [{ "id": "basemap", "url": "mapbox://styles/mapbox/standard" }],
  "sources": {},
  "layers": []
}
```

Load the style JSON like any other style:

**Android View**

```kotlin
mapView.mapboxMap.loadStyle(albersStyleJson)
```

**Jetpack Compose**

```kotlin
MapboxMap(
  style = { MapStyle(style = albersStyleJson) }
)
```

Important notes about using projections in a style:

-   A projection defined in a [style JSON file](https://docs.mapbox.com/android/maps/guides/styles/set-a-style/) must be a JSON object, for example `"projection": { "name": "albers" }`. The Maps SDK ignores a projection written as a string, such as `"projection": "albers"`.
-   If you define one projection in a style, and set a different one at runtime, then the runtime projection will be used.

## Set a projection at runtime

To change the projection of the current style, use [`setProjection`](https://docs.mapbox.com/android/maps/api/latest/mapbox-maps-android/com.mapbox.maps.extension.style.projection.generated/set-projection.html) with a [`ProjectionName`](https://docs.mapbox.com/android/maps/api/latest/mapbox-maps-android/com.mapbox.maps.extension.style.layers.properties.generated/-projection-name/):

```kotlin
mapView.mapboxMap.getStyle { style ->
  style.setProjection(projection(ProjectionName.GLOBE))
}
```

`ProjectionName` includes `GLOBE` and `MERCATOR`.

> **Note (warning): Albers is not in the SDK API yet**
> 
> Albers is not part of the Maps SDK API yet: there is no `ProjectionName` constant for it, and setting or reading it at runtime is not officially supported. To use Albers, [set it in your style JSON](#set-a-projection-in-a-style).

## Globe

![Globe projection in the Maps SDK for Android](https://docs.mapbox.com/android/assets/ideal-img/maps-guides-projections-globe.189eff4.480.png)

The Globe projection (defined as `globe` in the Maps SDK) is a three-dimensional representation of the earth. Globe increases the sense of depth of the map and is a correct representation of the surface of the earth as viewed from space. Using this projection limits the display of the earth to one hemisphere at a time. This can be addressed in some cases by rotating the globe with camera animation.

Globe is the default projection in Mapbox Standard. As you zoom in, the map transitions from the globe to the Mercator projection.

> **Related content (example): [Create a rotating globe](https://docs.mapbox.com/android/maps/examples/android-view/create-a-rotating-globe/)**
> 
> Rotate the globe with camera animation.

## Mercator

![Mercator projection in the Maps SDK for Android](https://docs.mapbox.com/android/assets/ideal-img/maps-guides-projections-mercator.10982b2.480.png)

The [Web Mercator](https://en.wikipedia.org/wiki/Web_Mercator_projection) projection (defined as `mercator` in the Maps SDK) is a cylindrical, conformal projection and the default projection in the Maps SDK if projection is not specified in a style. Web Mercator is classified as [EPSG:3857](https://epsg.io/3857) and is a variant of the classic [Mercator](https://en.wikipedia.org/wiki/Mercator_projection) projection used for marine navigation.

Mercator accurately displays shapes and angles, which makes it useful for navigation. At the world scale, it exaggerates the size of geographic shapes near the poles. For example, Greenland appears the same size as Africa, even though it's 14 times smaller.

Mercator is suitable for maps remaining at high zoom or cases where a map needs to cover the 180th meridian.

## Albers

![Albers projection in the Maps SDK for Android](https://docs.mapbox.com/android/assets/ideal-img/maps-guides-projections-albers.ba56f37.480.png)

The [Albers projection](https://en.wikipedia.org/wiki/Albers_projection) (defined as `albers` in the Maps SDK) is a conic, equal-area projection. This projection provides accurate relative sizes, but shapes are increasingly distorted at further distances.

The Albers projection is centered on the mainland United States at `[-96, 37.5]` with the standard parallels `[29.5, 45.5]`. The Maps SDK doesn't support the `center` and `parallels` options yet. 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.

Albers is an adaptive projection: it adjusts the projection as you zoom in to reduce distortion at all zoom levels by gradually transitioning from Albers to Web Mercator (which is optimal on higher zooms).

Composite Albers projection (for example where Alaska and Hawaii are alongside the mainland U.S.) is not yet supported in the Maps SDK.

## Limitations of Albers

Albers doesn't support all features that Globe and Mercator support. We plan to add support for these features in a future release.

### 3D and background styling

3D terrain and 3D landmarks can only be used with Globe and Mercator projections.

Atmospheric styling is also supported only in Globe and Mercator projections. In other projections, the empty area around the world is rendered black.