API reference - Points

If you know the discrete points you want to query, you can use the /v1/elevation/points endpoint to get the elevation above sea level of each location in a single request. POST requests are supported for large numbers of points.

Otherwise, GPXZ can evenly sample points along a path using the /v1/elevation/sample endpoint.

/v1/elevation/points

Query elevation at multiple multiple points. This is a batch version of /v1/elevation/point.

HTTP request

GET https://api.gpxz.io/v1/elevation/points?latlons=46.66,14.03|46.60,14.15

Example response

{
  "results": [
    {
    "elevation": 951.740417, 
    "lat": 46.66, 
    "lon": 14.03, 
    "data_source": "austria_10m_dtm", 
    "resolution": 10
  }, 
  {
    "elevation": 671.916199, 
    "lat": 46.6, 
    "lon": 14.15, 
    "data_source": "austria_10m_dtm", 
    "resolution": 10
  }
], 
"status": "OK"
}

Request query parameters

latlons: latitude,longitude pairs separated by a pipe.
polyline: Points encoded as a polyline. One of latlons or polyline must be provided.
bathymetry: if true return distance below sea level for points on the ocean (i.e., elevation will be negative). If false return 0 for points on the ocean. Default: false.
interpolation: which algorithm to use for interpolating between pixels in the underlying raster data. bilinear is smoother if displaying multiple points, but is slower and may reduce the extremity of peaks and troughs. Options: nearest, bilinear. Default: bilinear.

Response

A json object. Results are in the same order as the input points.

results[].elevation: elevation in metres at the provided point.
results[].lat: parsed latitude.
results[].lon: parsed longitude.
results[].data_source: ID of the open data source was used to build this area of the GPXZ dataset. You can use this ID to lookup more details with the /v1/elevation/sources endpoint.
results[].resolution: approximate resolution in metres of the GPXZ dataset in this area.
status: will be OK for successful request.

POST requests

When querying a large number of points in a single request, some software can't handle the length of the URL this produces. To get around this limitation, you can also send POST requests to /v1/elevation/points.

Request arguments should be provided as application/x-www-form-urlencoded:

import requests
    
API_KEY = "ak_123456_abcdef"

data = {
    'latlons': '40,91|-20,120',
    'interpolation': 'nearest',
}

response = requests.post(
    'https://api.gpxz.io/v1/elevation/points',
    headers={'x-api-key': API_KEY},
    data=data,
)

or as application/json:

curl -X POST \
    -H "Content-Type: application/json" \
    -H "X-Api-Key: YOUR-API-KEY-HERE" \
    -d '{"latlons": "40,91|-20,120", "interpolation": "nearest"}' \
    https://api.gpxz.io/v1/elevation/points

/v1/elevation/sample

Query elevation at evenly spaced points sampled along a given path.

For example, if you gave irregularly-spaced GPS data and want to show an elevation profile, you would provide the GPS coordinates as the path, and get back elevation data you can plot directly.

The first and last points returned will be the first and last points of the provided path. Your path can be up to 5,000 points long.

For more details about the sampling algorithm see Sampling points along a path.

HTTP request

GET https://api.gpxz.io/v1/elevation/sample?latlons=30.70,-82.22|30.70,-82.27&samples=4

Example response

{
  "results": [
    {
      "elevation": 36.886948, 
      "lat": 30.7, 
      "lon": -82.22, 
      "data_source": "us_3dep_10m", 
      "resolution": 10
    }, 
    {
      "elevation": 37.016758, 
      "lat": 30.700002138895783, 
      "lon": -82.23666666654412, 
      "data_source": "us_3dep_10m", 
      "resolution": 10
    }, 
    {
      "elevation": 36.937859, 
      "lat": 30.700002138895783, 
      "lon": -82.25333333345586, 
      "data_source": "us_3dep_10m", 
      "resolution": 10
    }, 
    {
      "elevation": 37.076237, 
      "lat": 30.7, 
      "lon": -82.27, 
      "data_source": "us_3dep_10m", 
      "resolution": 10
    }
  ], 
  "status": "OK"
}

Request query parameters

latlons: latitude,longitude pairs separated by a pipe, representing the path to sample along.
polyline: Path points encoded as a polyline. One of latlons or polyline must be provided.
samples: Number of points to sample along the path. Must be at least 2, and a maximum of 512. Required.
bathymetry: if true return distance below sea level for points on the ocean (i.e., elevation will be negative). If false return 0 for points on the ocean. Default: false.
interpolation: which algorithm to use for interpolating between pixels in the underlying raster data. bilinear is smoother if displaying multiple points, but is slower and may reduce the extremity of peaks and troughs. Options: nearest, bilinear. Default: bilinear.

Response

The response is the same as /v1/elevation/points.

POST requests

To avoid problems with URL length, you can send POST requests the same as /v1/elevation/points.