API documentation
This page explains how to access the gpxz.io API. To learn more about the elevation data used, see GPXZ dataset docs.
Contents
- 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
(orInfinity
orNaN
) 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
: iftrue
return distance below sea level for points on the ocean (i.e., elevation will be negative). Iffalse
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 beOK
for successful request,INVALID_REQUEST
for a client (4xx) error, andSERVER_ERROR
for anything else (5xx).error
: Description of what went wrong when status isn'tOK
.
/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 oflatlons
orpolyline
must be provided.bathymetry
: iftrue
return distance below sea level for points on the ocean (i.e., elevation will be negative). Iffalse
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 beOK
for successful request,INVALID_REQUEST
for a client (4xx) error, andSERVER_ERROR
for anything else (5xx).error
: Description of what went wrong when status isn'tOK
.
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 oflatlons
orpolyline
must be provided.samples
: Number of points to sample along the path. Must be at least 2. Required.bathymetry
: iftrue
return distance below sea level for points on the ocean (i.e., elevation will be negative). Iffalse
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 theerror_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 ofjson
orxml
. 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 beOK
for successful request,INVALID_REQUEST
for a client (4xx) error, andSERVER_ERROR
for anything else (5xx).error_message
: Description of what went wrong when status isn'tOK
.
/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 tootd-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 beOK
for successful request,INVALID_REQUEST
for a client (4xx) error, andSERVER_ERROR
for anything else (5xx).error_message
: Description of what went wrong when status isn'tOK
.
/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 thedata_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 beOK
for successful request,INVALID_REQUEST
for a client (4xx) error, andSERVER_ERROR
for anything else (5xx).error
: Description of what went wrong when status isn'tOK
.
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 beOK
for successful request,INVALID_REQUEST
for a client (4xx) error, andSERVER_ERROR
for anything else (5xx).