All docsHelpTroubleshootingAccess elevation data

Access elevation data

-There are two different Mapbox tilesets that contain elevation data:

This guide explains what each tileset is used for and how to access its elevation data.

Mapbox Terrain-RGB

The Mapbox Terrain-RGB tileset contains global elevation data encoded in raster PNG tiles as color values that can be decoded to raw heights in meters. You can use Terrain-RGB for a wide variety of applications both visual and analytical, from styling terrain slope and hillshades to generating 3D terrain meshes for video games.

Some specifics about Mapbox Terrain-RGB:

  • Data up to zoom 15. The data is encoded to the equivalent of zoom 15 at 256 tile resolution (and zoom 14 for 512 tiles). Any higher zoom levels will not increase the resolution of the data loaded by your application.
  • 0.1 meter height increments. Data is mapped to 0.1 meter height increments, which gives it the vertical precision necessary for cartographic and 3D applications.

Request data

You can use this Raster Tiles API endpoint to get Mapbox Terrain-RGB tiles:

https://api.mapbox.com/v4/mapbox.terrain-rgb/{zoom}/{x}/{y}.pngraw?access_token=YOUR_MAPBOX_ACCESS_TOKEN

Example request: Retrieve a Terrain-RGB tile

# Retrieve a Terrain-RGB tile at zoom 14, centered on Omaha, Nebraska
$ curl "https://api.mapbox.com/v4/mapbox.terrain-rgb/14/12558/6127.pngraw?access_token=YOUR_MAPBOX_ACCESS_TOKEN" --output test.pngraw

Things to note about this request:

  • Be sure you are requesting pngraw tiles.
  • By default, the service returns 256×256 tiles. You can use @2x to request 512×512 tiles. Requesting 512×512 tiles is sometimes preferable because it means fewer total requests over a given area.
  • Be sure you are using x and y tilename values, not geographic longitude and latitude coordinates. If you need to convert geographic coordinates to the tile coordinate names used in Slippy Map tilenames, you can use one of the libraries listed here .

Decode data

Mapbox Terrain-RGB uses each RGB color channel as a position in a base-256 numbering system, allowing for 16,777,216 unique values. Once you receive the tiles, you will need to get the red (R), green (G), and blue (B) values for individual pixels. You can do this using a canvas layer in your browser (example) or using a tool like get-pixel.

The following equation will decode pixel values to height values. The height will be returned in meters.

height = -10000 + ((R * 256 * 256 + G * 256 + B) * 0.1)

Identify tiles to request

While working with Mapbox Terrain-RGB, you may need to develop your own workflow to identify which tiles you will need. We recommend checking out the tools below to identify and request the tiles you require:

  • mercantile: a module of utilities for working with XYZ-style spherical mercator tiles and includes a set of command line programs built on these utilities.
  • supermercado: extends the functionality of Mercantile with additional commands.
  • tilebelt: a set of JavaScript utilities for requesting and working with tiles.
  • tile-cover: a JavaScript library that generates the minimum number of tiles required to cover a GeoJSON Geometry.
  • xt: allows you to automatically convert a stream of tile coordinates to another format.

Tiles in water areas

Requests made to the Terrain-RGB endpoint where a tile is fully encompassed by oceanic water areas will return the following:

{
  message: "Tile does not exist"
}

This message is expected, given that there is no terrain to represent in water areas. A "Tile does not exist" message should be interpreted as elevation 0 in the context of Terrain-RGB.

To access and style ocean depth data, you can add bathymetry source data to your map as demonstrated in this example.

Mapbox Terrain vector tileset

The Mapbox Terrain vector tileset includes features like topography, hillshades, and landcover. The features in the contour source layer contain a property called ele, which is an elevation value in meters.

Some specifics about Mapbox Terrain:

  • Data is mapped to 10 meter height increments.
  • Index field can be used to highlight index contour lines or control the density of contours on the map.

Request data

To work directly with the elevation data in the Mapbox Terrain tileset, you can retrieve features from vector tiles at a given point using the Mapbox Tilequery API.

https://api.mapbox.com/v4/mapbox.mapbox-terrain-v2/tilequery/{lon},{lat}.json?&access_token=YOUR_MAPBOX_ACCESS_TOKEN
Query elevation along a line

The Mapbox Tilequery API allows you to query features at a single point. To find elevation along a line, you will have to turn your line into a series of points. You can do this using turf.js.

const points = turf.explode(line); // where line is a GeoJSON LineString

Example request: Query features at a single point

# Query map features at a single point near Omaha, Nebraska.
$ curl "https://api.mapbox.com/v4/mapbox.mapbox-terrain-v2/tilequery/95.9345,41.2565.json?access_token=YOUR_MAPBOX_ACCESS_TOKEN"

Get elevation

The above request will return a GeoJSON FeatureCollection of all the features that exist at the given point, some of which have elevation data (ele). When working with the returned data, there are a couple of considerations:

  1. Because the elevation data you want is included in the contour layer, you will need to parse the returned GeoJSON to isolate the features from the contour layer.
  2. In the Mapbox Terrain tileset, contours are comprised of stacked polygons, which means most of your requests will return multiple features from the contour layer. You will likely need to parse the returned GeoJSON to find the highest elevation value.