API reference - Compatibility

Drop-in endpoints that let you migrate from other services.

/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.