Elevation API reference

Estimated reading time: 6 minutes

Elevation API

The Elevation API provides elevation data above the sea level for any location on Earth’s surface. The Elevation API allows you to retrieve sampled elevation data along a path. This can be useful for hiking, biking or motorcycling applications.

Elevation values

The elevation values are expressed in meters above the sea level. That is if you query for locations in the middle of the ocean the elevation value will be 0 meters.

Location coordinates

The location coordinates are expressed in WGS 84 Web Mercator coordinate system as a pair of (latitude,longitude).
Example: (48.856578,2.351828)

The latitude extent is [-85.05113, +85.05113]
The longitude extent is [-180.0, +180.0]

Path

A path is an ordered list of location coordinates.

Elevation precision

The precision of the elevation value is relative to the path extent. The wider the path is, the less accurate the elevation will be.
If you require high precision, consider to split your path in smaller paths and perform one request for each.

Access token

Before accessing the Elevation API, you need a valid access token. You can get your access tokens in your Jawg Lab account

Endpoints

Since the URL may be very long each GET endpoint has a POST alternative.

:warning: All GET request parameters must be url encoded.

Request elevations for a set of locations

To get the elevation values for a set of locations, use the following endpoints:

https://api.jawg.io/elevations?locations={locations}&access-token={your-access-token}
https://api.jawg.io/elevations/locations?access-token={your-access-token}

{
 "locations": "{locations}"  
}

Request parameters

  • locations required: A set of 1 to 500 location coordinates that can take two forms:
    1. An array of two or more location coordinates lat,lng separated by a pipe character '|': 48.856578,2.351828|44.837912,-0.579541
    2. A set of location coordinates encoded using Encoded Polyline Algorithm: sheiH}ijMt{oW`p{P
  • access-token required: Your access token available in your Jawg Lab account: your-access-token

Request elevations along a path

To get the elevation values along a path, use the following endpoint:

https://api.jawg.io/elevations?path={path}&samples={samples}&access-token={your-access-token}
https://api.jawg.io/elevations/path?access-token={your-access-token}

{
 "path": "{path},
 "samples": {samples}
}

Request query parameters

  • path required: A succession 1 to 500 locations coordinates that can take two forms:
    1. An array of two or more location coordinates lat,lng separated by a pipe character '|': 48.856578,2.351828|44.837912,-0.579541
    2. A set of location coordinates encoded using Encoded Polyline Algorithm: sheiH}ijMt{oW`p{P
  • samples required: An integer between 1 and 1024 that specifies the number of sample points along the path. The sample points are equidistant along the path: 3
  • access-token required: Your access token available in your Jawg Lab account: your-access-token

Response

For both endpoints, the response is a JSON array of elevation sample points with the following fields:

  • elevation: The elevation value above the sea level in meters.
  • location: The sample point coordinates.
  • resolution: The size in meters of the area from which the elevation was calculated.

Examples

Request elevation values by location set

The following examples request the elevation values at 3 locations: Marseille, Toulouse and Lyon.

Piped locations:

https://api.jawg.io/elevations?locations=43.296346,5.369889%7C43.604482,1.443962%7C45.759723,4.842223&access-token=your-access-token
https://api.jawg.io/elevations/locations?access-token=your-access-token

{
  "locations": "43.296346,5.369889|43.604482,1.443962|45.759723,4.842223"
}

Polyline locations

https://api.jawg.io/elevations?locations=eiggGyxw_%40yd%7B%40%60x%7DVg%7DcLcvvS&access-token=your-access-token
https://api.jawg.io/elevations/locations?access-token=your-access-token

{
  "locations": "eiggGyxw_@yd{@`x}Vg}cLcvvS"
}

Response

[
    {
        "elevation": 0.0,
        "location": {
            "lat": 43.296346,
            "lng": 5.369889
        },
        "resolution": 445.05704286596927
    },
    {
        "elevation": 149.60059,
        "location": {
            "lat": 43.604482,
            "lng": 1.443962
        },
        "resolution": 442.7953748275146
    },
    {
        "elevation": 178.5,
        "location": {
            "lat": 45.759723,
            "lng": 4.842223
        },
        "resolution": 426.621899544754
    }
]

Request elevation values along a path

The following examples request the elevation values along a path from Paris to Bordeaux.

Piped path:

https://api.jawg.io/elevations?path=48.856578,2.351828%7C44.837912,-0.579541&samples=3&access-token=your-access-token
https://api.jawg.io/elevations/path?access-token=your-access-token

{
  "path": "48.856578,2.351828|44.837912,-0.579541",
  "samples": 3
}

Polyline path

https://api.jawg.io/elevations?path=sheiH%7DijMt%7BoW%60p%7BP&samples=3&access-token=your-access-token
https://api.jawg.io/elevations/path?access-token=your-access-token

{
  "path": "sheiH}ijMt{oW`p{P",
  "samples": 3
}

Response

[
    {
        "elevation": 34.700195,
        "location": {
            "lat": 48.856578,
            "lng": 2.351828
        },
        "resolution": 804.6631821405058
    },
    {
        "elevation": 112.40039,
        "location": {
            "lat": 46.847245,
            "lng": 0.8861435
        },
        "resolution": 836.4605331418809
    },
    {
        "elevation": 18.40039,
        "location": {
            "lat": 44.837912,
            "lng": -0.579541
        },
        "resolution": 867.2292533709178
    }
]