Elevation

Estimated reading time: 3 minutes

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 pairs 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. There are 2 formats for encoding:

  • Locations separated by the Pipe character (|) URL-encoded as %7C
  • Locations encoded as a Polyline
43.296346,5.369889%7C43.604482,1.443962%7C45.759723,4.842223
eiggGyxw_%40yd%7B%40%60x%7DVg%7DcLcvvS

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.

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}
// POST 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}
// POST 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}
// POST 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}
// POST 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}
// POST 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}
// POST 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
  }
]