Skip to main content

Access elevation data

Additional Developer Resources

Elevation data are elevation measurements for locations distributed over the land surface. Such data can be used to create a Digital Elevation Model (DEM), which is a representation of the topographic surface of the Earth.

Several Mapbox tilesets contain elevation data:

  • Mapbox Terrain-RGB and Mapbox Terrain-DEM contain elevation data in Terrain-RGB tiles.
  • Mapbox Terrain contains features with an ele property for elevation values.

This guide describes advantages and disadvantages of each tileset, and explains how you can access the elevation data in these tilesets.

Use Mapbox GL JS​

If you are using Mapbox GL JS to build a web application, you can use queryTerrainElevation to access data in the map:

const coordinate = [-122.420679, 37.772537];
const elevation = map.queryTerrainElevation(coordinate);

See the Query terrain elevation along a line example:

Use the Raster Tiles API​

To access elevation data encoded in Terrain-RGB tiles like those contained in the Mapbox Terrain-RGB and Mapbox Terrain-DEM tilesets, you can use the Raster Tiles API.

Request data​

To request a raster tile, use this Raster Tiles API endpoint:

https://api.mapbox.com/v4/mapbox.terrain-rgb/{zoom}/{x}/{y}{@2x}.pngraw?access_token=YOUR_MAPBOX_ACCESS_TOKEN
  • {x} and {y} are 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.
  • @2x is an optional parameter to request 512×512 tiles instead of the default 256×256 tiles. Requesting 512×512 tiles can be preferable because it means fewer total requests over a given area.
  • pngraw is the output format you must use when requesting Terrain-RGB tiles.
  • To use mapbox.mapbox-terrain-dem-v1 instead of mapbox.terrain-rgb tileset, you will need a SKU token, as shown in the reference documentation.

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/3826/6127.pngraw?access_token=YOUR_MAPBOX_ACCESS_TOKEN" --output test.pngraw

Response: Retrieve a Terrain-RGB tile​

The response is a raster image tile in the specified format.

Decode data​

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 elevation values. The elevation will be returned in meters.

elevation = -10000 + (({R} * 256 * 256 + {G} * 256 + {B}) * 0.1)

Example: Decode elevation data in a Terrain-RGB tile​

In the example response above, the top-right pixel has an RGB color value of rgb(1,150,136). We can use those values with the equation:

elevation = -10000 + ((1 * 256 * 256 + 150 * 256 + 136) * 0.1)

The equation calculates the elevation of that location to be 407.2 meters.

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.

Use the Tilequery API​

To access elevation data the Mapbox Terrain vector tileset, you can use the Tilequery API.

Mapbox Terrain includes features in the contour source layer that contain a property called ele, which is an elevation value in meters.

  • 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 retrieve features from vector tiles at a given point, use this Mapbox Tilequery API endpoint:

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.jsconst 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"

Response: Query features at a single point​

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).

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "id": 1,
      "geometry": { "type": "Point", "coordinates": [95.9345, 41.2565] },
      "properties": {
        "ele": 1920,
        "index": 2,
        "tilequery": {
          "distance": 0,
          "geometry": "polygon",
          "layer": "contour"
        }
      }
    },
    {
      "type": "Feature",
      "id": 2,
      "geometry": { "type": "Point", "coordinates": [95.9345, 41.2565] },
      "properties": {
        "ele": 1930,
        "index": 1,
        "tilequery": {
          "distance": 0,
          "geometry": "polygon",
          "layer": "contour"
        }
      }
    },
    {
      "type": "Feature",
      "id": 3,
      "geometry": { "type": "Point", "coordinates": [95.9345, 41.2565] },
      "properties": {
        "ele": 1940,
        "index": 2,
        "tilequery": {
          "distance": 0,
          "geometry": "polygon",
          "layer": "contour"
        }
      }
    }
  ]
}

Get elevation​

When working with the returned data, consider these factors:

  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.

Data updates​

Elevation data is not improved on a set schedule and is updated when and where it becomes available.

Additional Developer Resources
Was this page helpful?