Access elevation data
There are two different Mapbox tilesets that contain elevation data:
- Mapbox Terrain-RGB, a raster tileset.
- Mapbox Terrain, a vector tileset.
This guide explains what each is used for and how to access the data.
Mapbox Terrain-RGB 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 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.
You can use the following endpoint to get Terrain-RGB tiles.
Two things to note about this request:
- Be sure you are requesting
- By default, 256x256 tiles are returned. You can use
@2xto request 512x512 tiles. Requesting 512x512 tiles is sometimes preferable as it means fewer total requests over a given area.
Terrain-RGB uses each 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)
While working with 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.
- xt: allows you to automatically convert a stream of tile coordinates to another format.
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.
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.
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 to keep in mind:
- Because the elevation data you want is included in the
contourlayer, you will need to parse the returned GeoJSON to isolate the features from the
- In the Mapbox Terrain tileset, contours are comprised of stacked polygons, which means most of your requests will return multiple features from the
contourlayer. You will likely need to parse the returned GeoJSON to find the highest elevation value.