API documentation

This page explains how to access the gpxz.io API. To learn more about the elevation data used, see GPXZ dataset docs.

General notes
Authentication
/v1/elevation/point - elevation of a single location
/v1/elevation/points - elevation of multiple locations
/v1/elevation/sample - elevation of locations evenly sampled along a path
/v1/elevation/gmaps-compat - Google Maps Elevation API replacement
/v1/elevation/otd-compat - Open Topo Data API replacement
/v1/elevation/sources - details about source elevation data
/v1/health - API status

General notes

Longitudes should be in the range [-180, 180].
The GPXZ dataset doesn't have any holes or missing data, so the API will never return null (or Infinity or NaN) as an elevation.
Elevations values are returned with lots of decimal points. This is for implementation simplicity and interpolation smoothness, not because the data is millimetre-accurate. You should round numbers before displaying to end users.
All latitude/longitude coordinates are in EPSG:4326 (aka WGS84) format.

Authentication

An API key is needed to access the GPXZ API. After signing up for an account, you can view and copy your keys on the API keys tab in the dashboard.

Include one of you API keys as the value of the x-api-key header on requests. In python, this might look like

import requests

API_KEY = "ak_123456_abcdef"

response = requests.get(
    "https://api.gpxz.io/v1/elevation/point?lat=1&lon=2",
    headers={"x-api-key": API_KEY},
)
print(response.json())

To make in-browser testing easier, you can also include the key in the url with a query parameter called api-key

https://api.gpxz.io/v1/elevation/point?lat=1&lon=2&api-key=ak_123456_abcdef

/v1/elevation/point

Query the elevation at a single point.

HTTP request

GET https://api.gpxz.io/v1/elevation/point?lat=57.66&lon=11.90

Example response

{
  "result": {
    "elevation": 38.263489, 
    "lat": 57.66, 
    "lon": 11.9, 
    "data_source": "copernicus_30m", 
    "resolution": 30
  }, 
  "status": "OK"
}

Request query parameters

lat: latitude, in degrees. Required.
lon: longitude, in degrees. 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

A json object.

result.elevation: elevation in metres at the provided point.
result.lat: parsed latitude.
result.lon: parsed longitude.
result.data_source: which open dataset was used to build this area of the GPXZ dataset.
result.resolution: approximate resolution in metres of the GPXZ dataset in this area.
status: will be OK for successful request, INVALID_REQUEST for a client (4xx) error, and SERVER_ERROR for anything else (5xx).
error: Description of what went wrong when status isn't OK.

/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: which open dataset was used to build this area of the GPXZ dataset.
results[].resolution: approximate resolution in metres of the GPXZ dataset in this area.
status: will be OK for successful request, INVALID_REQUEST for a client (4xx) error, and SERVER_ERROR for anything else (5xx).
error: Description of what went wrong when status isn't OK.

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: ak_123456_abcdef" \
  -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 5000 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. 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.

/v1/elevation/gmaps-compat/<outputFormat>

If you're currently using the Google Maps Elevation API, you can migrate to GPXZ by replacing

https://maps.googleapis.com/maps/api/elevation/

with

https://api.gpxz.io/v1/elevation/gmaps-compat/

and changing the API key to your GPXZ one.

All features of the Google Maps API are supported, including xml output and sampled paths. See Google's API docs for a detailed description of the API.

For compatibility with Google Maps, this endpoint always returns bathymetry (ocean depth). If you need 0-elevation results over water, please use one of the GPXZ endpoints instead.

Known differences between Google's API and this endpoint:

The Google API reduces the elevation accuracy of multi-point queries. GPXZ returns full accuracy elevation values for each request.
The Google API is limited to 512 points per request and 100 requests per second. When using the GPXZ gmaps-compat endpoint your plan's limits will still apply.
Invalid requests all return the status INVALID_REQUEST. To differentiate between error types you'll need to read the error_message field or parse the response HTTP status code.
To preserve compatibility, data attribution information is returned as a x-data-sources header rather than as part of the response body.

HTTP request

GET https://api.gpxz.io/v1/elevation/gmaps-compat/json?locations=38.099,-119.597

Example response

{
  "results" : [
    {
      "elevation" : 2858.26416, 
      "location" : {
        "lat" : 38.099, 
        "lng" : -119.597
      }, 
      "resolution" : 10
    }
  ], 
  "status" : "OK"
}

URL path parameters

outputFormat: one of json or xml. Required. Default: json.

Request query parameters

locations: latitude,longitude pairs separated by a pipe, or a polyline string. Required for positional queries.
path: latitude,longitude pairs separated by a pipe, or a polyline string. Required for sampled queries.
samples: number of points along path to sample. Required for sampled queries.
key: your GPXZ API key (not a Google Maps key). Required.

Response

A json object or xml.

results[].elevation: elevation in metres at the provided point.
results[].location.lat: parsed latitude.
results[].location.lng: parsed longitude.
results[].resolution: approximate resolution in metres of the GPXZ dataset in this area.
status: will be OK for successful request, INVALID_REQUEST for a client (4xx) error, and SERVER_ERROR for anything else (5xx).
error_message: Description of what went wrong when status isn't OK.

/v1/elevation/otd-compat

If you're currently using the Open Topo Data API, you can migrate to GPXZ by replacing

https://api.opentopodata.org/v1/<dataset_name>

with

https://api.gpxz.io/v1/elevation/otd-compat

and changing the API key to your GPXZ one.

Most features of the Open Topo Data API are supported: polyline format, path sampling, and POST requests.

There are a few potential differences though:

GPXZ doesn't support cubic interpolation. If this value is passed to otd-compat, bilinear interpolation is used instead.
Because the GPXZ dataset doesn't have any missing data, the nodata_value argument is ignored.

HTTP request

GET https://api.gpxz.io/v1/elevation/otd-compat?locations=38.099,-119.597

Example response

{
  "results" : [
    {
      "elevation" : 2858.26416, 
      "location" : {
        "lat" : 38.099, 
        "lng" : -119.597
      }, 
      "resolution" : 10
    }
  ], 
  "status" : "OK"
}

Request query parameters

locations: latitude,longitude pairs separated by a pipe, or a polyline string. Required for positional queries.
samples: number of points along path to sample.

Response

A json object.

results[].elevation: elevation in metres at the provided point.
results[].location.lat: parsed latitude.
results[].location.lng: parsed longitude.
results[].dataset: GPXZ data source.
status: will be OK for successful request, INVALID_REQUEST for a client (4xx) error, and SERVER_ERROR for anything else (5xx).
error_message: Description of what went wrong when status isn't OK.

/v1/elevation/sources

Information about all the source data used in GPXZ.

HTTP request

GET https://api.gpxz.io/v1/elevation/sources

Example response

{
  "results": [
    {
      "data_source": "us_3dep_10m", 
      "name": "US 3DEP 1/3 arc-second", 
      "resolution": 10, 
      "url": "https://www.usgs.gov/core-science-systems/ngp/3dep/about-3dep-products-services", 
      "organization": "USGS", 
      "attribution": "USGS 3D Elevation Program Digital Elevation Model"
    }, 
    {
      "data_source": "austria_10m_dtm", 
      "name": "Digital Elevation Model (DEM) Austria 10m", 
      "resolution": 10, 
      "url": "https://www.data.gv.at/katalog/dataset/b5de6975-417b-4320-afdb-eb2a9e2a1dbf", 
      "organization": "Land Kärnten", 
      "attribution": "CC-BY-4.0: Land Kärnten - data.gv.at"
    }
  ], 
  "status": "OK"
}

Response

A json object listing every source.

results[].data_source: gpxz source id, to be matched with the data_source field on other responses.
results[].name: full name of the dataset.
results[].resolution: approximate resolution in metres of the source dataset.
results[].url: link to more information from the dataset producer.
results[].organization: orgianisation (typically a government branch) that made the dataset.
results[].attribution: attribution statement (even if not required by the dataset license).
status: will be OK for successful request, INVALID_REQUEST for a client (4xx) error, and SERVER_ERROR for anything else (5xx).
error: Description of what went wrong when status isn't OK.

GET /v1/health

Healthcheck endpoint, for use with load balancing or monitoring.

HTTP request

GET https://api.gpxz.io/v1/health

Example response

{
  "status": "OK"
}

Response

A json object.

status: will be OK for successful request, INVALID_REQUEST for a client (4xx) error, and SERVER_ERROR for anything else (5xx).

API documentation

Contents

General notes

Authentication

/v1/elevation/point

HTTP request

Example response

Request query parameters

Response

/v1/elevation/points

HTTP request

Example response

Request query parameters

Response

POST requests

/v1/elevation/sample

HTTP request

Example response

Request query parameters

Response

POST requests

/v1/elevation/gmaps-compat/<outputFormat>

HTTP request

Example response

URL path parameters

Request query parameters

Response

/v1/elevation/otd-compat

HTTP request

Example response

Request query parameters

Response

/v1/elevation/sources

HTTP request

Example response

Response

GET /v1/health

HTTP request

Example response

Response