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

# Access elevation data

**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](https://docs.mapbox.com/help/glossary/tileset/) 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`](https://docs.mapbox.com/mapbox-gl-js/api/map/#map#queryterrainelevation) to access data in the map:

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

See the [Query terrain elevation along a line](https://docs.mapbox.com/mapbox-gl-js/example/elevation-along-line/) example:

## Use the Raster Tiles API

To access elevation data encoded in Terrain-RGB tiles like those contained in the [Mapbox Terrain-RGB](https://docs.mapbox.com/data/tilesets/reference/mapbox-terrain-rgb-v1/) tileset, you can use the Raster Tiles API.

### Request data

To request a raster tile, use this [Raster Tiles API](https://docs.mapbox.com/api/maps/raster-tiles/) 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](https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames), you can use [one of the libraries listed here](https://docs.mapbox.com/help/troubleshooting/access-elevation-data/#identify-tiles-to-request).
-   `@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.

#### Example request: Retrieve a Terrain-RGB tile

```bash
# 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](https://docs.mapbox.com/api/maps/raster-tiles/#response-retrieve-raster-tiles) is a raster image tile in the specified format.

![The response includes a raster map tile with elevation data encoded as RGB.](https://docs.mapbox.com/assets/ideal-img/guide-access-elevation-data-example-response.480.png)

### 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](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D) in your browser ([example](https://www.mapbox.com/bites/00307/?elev=10#8/38.055/-121.976)) or using a tool like [get-pixel](https://github.com/scijs/get-pixels).

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](https://github.com/mapbox/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](https://github.com/mapbox/supermercado): extends the functionality of Mercantile with additional commands.
-   [tilebelt](https://github.com/mapbox/tilebelt): a set of JavaScript utilities for requesting and working with tiles.
-   [tile-cover](https://github.com/mapbox/tile-cover): a JavaScript library that generates the minimum number of tiles required to cover a GeoJSON Geometry.
-   [xt](https://github.com/mapbox/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](https://docs.mapbox.com/mapbox-gl-js/example/style-ocean-depth-data/).

## Use the Tilequery API

To access elevation data the [Mapbox Terrain](https://docs.mapbox.com/data/tilesets/reference/mapbox-terrain-v2/) vector tileset, you can use the Tilequery API.

Mapbox Terrain includes features in the `contour` [source layer](https://docs.mapbox.com/help/glossary/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](https://docs.mapbox.com/api/maps/#tilequery) endpoint:

```
https://api.mapbox.com/v4/mapbox.mapbox-terrain-v2/tilequery/{lon},{lat}.json?&access_token=YOUR_MAPBOX_ACCESS_TOKEN 
```

> **Note: Query elevation along a line**
> 
> The Mapbox Tilequery API allows you to [query features at a single point](https://docs.mapbox.com/api/maps/#tilequery). 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](https://turfjs.org/docs/api/explode).`jsconst points = turf.explode(line); // where line is a GeoJSON LineString`

#### Example request: Query features at a single point

```bash
# 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`).

```json
{
  "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.