gpxz

Terrain tiles API

2026-08-11T00:00:00-05:00

The GPXZ API now has terrain tiles!

There’s a TileJSON endpoint

https://api.gpxz.io/v1/elevation/tiles.json?api_key=replace_with_your_gpxz_api_key

and an XYZ / slippymap endpoint

https://api.gpxz.io/v1/elevation/tile/{z}/{x}/{y}.png?api_key=replace_with_your_gpxz_api_key

both with support for png and webp images, mapbox and terrarium DEM encoding, and various tile size options to accomodate high-dpi retina screens.

Application

XYZ tiles (and TileJSON) are a standard format for defining terrain map tiles. They’re supported by most geospatial mapping software, and make it easy to migrate from other tile providers such as Mapterhorn, Mapbox or Mapzen.

You can add them to GIS software like QGIS for analysis:

Or use GPXZ data in a webmap with MapLibre

<!DOCTYPE html>
<html lang="en">
<head>
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link rel='stylesheet' href='https://unpkg.com/maplibre-gl@5.24.0/dist/maplibre-gl.css' />
    <script src='https://unpkg.com/maplibre-gl@5.24.0/dist/maplibre-gl.js'></script>
    <style>
        body {
            margin: 0;
            padding: 0;
        }
        html, body, #map {
            height: 100%;
        }
    </style>
</head>

<body>
    <div id='map'></div>
    <script>
        const map = new maplibregl.Map({
            container: 'map',
            zoom: 10,
            center: [11.491, 47.274],
            pitch: 0,
            hash: true,
            style: {
                version: 8,
                sources: {
                    hillshadeSource: {
                        type: 'raster-dem',
                        tiles: ['https://api.gpxz.io/v1/elevation/tile/{z}/{x}/{y}@2x.png?api_key=replace_with_your_gpxz_api_key'],
                        encoding: 'terrarium',
                        tileSize: 512,
                        maxzoom: 18
                    },
                },
                layers: [
                    {
                        id: 'hillshade',
                        type: 'hillshade',
                        source: 'hillshadeSource',
                        paint: {
                            'hillshade-method': 'standard',
                            'hillshade-illumination-direction': 315,
                            'hillshade-shadow-color': '#000000',
                            'hillshade-highlight-color': '#FFFFFF',
                            'hillshade-accent-color': '#000000',
                            'hillshade-exaggeration': 0.5
                        }
                    },

                ]
            },
            maxZoom: 18,
            maxPitch: 85
        });
    </script>
</body>
</html>

Access

Terrain tile access is included in all plans, including the free plan. There’s a different (higher) quota compared to regular API requests.

You’ll need to use an API key with the tiles scope. We recommend creating a new tightly-scoepd API key for each tiles project, and using some of the other methods we have to secure API keys by restricting their use to a certain domain.

Check out the tile API documentation for full details, or reach out to support@gpxz.io with any questions. Happy mapping!

Securing GPXZ API keys in webapps

2026-05-28T00:00:00-05:00

Most requests to the GPXZ API require an API key.

Typically, these keys are kept private inside an application and not exposed to end users. However, web-based and mobile applications run on end users’ devices, where it’s possible to extract the key.

If you need to make an API key public, we recommend at least creating an application-specific key with minimal scopes and domain restriction.

CORS header

By default, the GPXZ API sends responses with the header access-control-allow-origin: * . This means you can make requests from a browser-based application: such requests are sometimes called AJAX or XHR requests.

If you would like to rescrict the origins which can send requests using a certain API key, you use the “access-control-allow-origin” setting on that key. A valid origin looks like this: https://www.example.com, it needes a scheme/protocol and a hostname/domain.

Note that a CORS restriction isn’t enough to keep your API key secure. If you include your key in a public application, anyone can see your key and use it to make non-browser-based requests.

Allowed domains

You can further limit access by adding domain restrictions to an API key. This means that the key will only work for requests that originate from the domains specified.

Domain restriction works by checking the Origin and Referer headers, which most browsers send on every request. Requests that don’t match an allowed domain will be blocked with a 403 status code.

Each allowed “domain” is technically a hostname: a domain plus optional subdomains. Requests from subdomains of the proided hostname are allowed: so www.example.com will match requests from a.b.c.www.example.com as well as from www.example.com, but not from api.example.com or example.com. You may want to include localhost for local testing.

There are some situations where the Referer headers isn’t sent: for example, privacy-focused browsers don’t set this header. Because of this, requests without either of these the Refer or Origin header will be allowed, even if allowed domains are specified.

Note that, just like a CORS restriction, if you make your API key public then the allowed domains restriction will only prevent unauthorised requests originating from a browser.

Scopes

Scopes let you restrict the endpoints which an API key can be used for, limiting that key’s usefulness for an unauthorised user.

Any API key, even with no scopes added, is able to access endpoints which don’t requuire authentication. This covers GPXZ’s meta endpoints

/v1/elevation/sources
/v1/elevation/supported-raster-projections
/v1/health

Proxying

To fully prevent leaking your API key, the “proper” solution is to run a service which proxies requests to GPXZ, injecting your API key at the proxying level.

In nginx, that would look something like

server {
    listen 80;
    server_name gpxz-proxy.example.com;

    location / {
        proxy_pass https://api.gpxz.io;
        proxy_set_header x-api-key "YOUR_GPXZ_API_KEY";
    }
}

That way, you can perform your own access control and abuse mitigation, such as rate-limiting and request validation.

Help!

Reach out if you need any help or are seeing unauthorised access of your API key: support@gpxz.io.

New raster endpoints

2026-05-17T00:00:00-05:00

GPXZ has a pair of new 2D raster endpoints, designed to replace the existing hires-raster endpoint.

/v1/elevation/raster generates rasters at any scale: from property parcels to entire countries. Resolution can be specified in metres, projected units, or pixels.
/v1/elevation/raw-raster generates small-scale, high-resolution rasters with minimal reprojection.

Both endpoints have increased area limits, improved performance, and better support for working with ocean depth and across multiple projections.

For more details, head over to the raster API documentation.

GeoTIFF rasters

The new /v1/elevation/raster endpoint is intended to cover the majority of usecases.

Define a bounding box

Basemap © OpenStreetMap

and provide the bounding coordinates to /v1/elevation/raster, along with your desired resolution

curl 'https://api.gpxz.io/v1/elevation/raster?'\
'bbox_left=172.81142&'\
'bbox_right=172.82887&'\
'bbox_bottom=-41.87380&'\
'bbox_top=-41.86548&'\
'resolution_m=1' \
  -H 'x-api-key: replace_with_your_gpxz_api_key'

Here’s the hillshaded result:

As well as a resolution in metres, you can also specify a raster shape in pixels, which can make more sense for large-scale rasters

Just use height_px and width_px:

curl 'https://api.gpxz.io/v1/elevation/raster?'\
'bbox_left=-17.62&'\
'bbox_right=8.51&'\
'bbox_bottom=35.37&'\
'bbox_top=44.46&'\
'height_px=1000&' \
'width_px=2000&' \
  -H 'x-api-key: replace_with_your_gpxz_api_key'

and the heatmap output:

This new raster enables a number of new usages

Generating an elevation raster that’s exactly aligned with the projection, resolution, and bounds of another raster.
Controlling whether you want water depth or a fixed value of 0 over oceans.
Querying rasters at arbitrary zoom levels.

There’s more info in the raster API documentation.

Raw rasters

The raster endpoint expands the control you get over raster outputs. Typically, projection and/or interpolation is done to enable this flexibility.

For customers who need only the highest quality raster outputs, with minimal processing, there is a new raw-raster endpoint. This aims to crop an extract out of our dataset without interpolation, where possible.

Only a bounding box is specified, no resolution.

curl 'https://api.gpxz.io/v1/elevation/raw-raster?'\
'bbox_left=172.81142&'\
'bbox_right=172.82887&'\
'bbox_bottom=-41.87380&'\
'bbox_top=-41.86548'\
  -H 'x-api-key: replace_with_your_gpxz_api_key'

To learn more, head over to the raw raster API documentation.

Migrating from /v1/elevation/hires-raster

If you’re already using the old raster endpoint, migration is easy.

If you are using res_m=best

Replace /v1/elevation/hires-raster with /v1/elevation/raw-raster
Remove the res_m and tight_bounds parameters
Add &bathymetry=true (as ocean depth was always included with raw-raster, whereas hires-raster lets you choose)

Otherwise if you are using a specific value for res_m (or the default value of 1):

Replace /v1/elevation/hires-raster with /v1/elevation/raster
Replace res_m with resolution_m
Remove the tight_bounds parameter
Add &bathymetry=true (as ocean depth was always included with raw-raster, whereas raster lets you choose)
Add &projection=utm if you’d still like UTM-projected outputs

Responses will be faster and are less likely to trigger interpolation/reprojection, and larger extract areas are allowed.

The old hires-raster raster endpoint will continue to function, and will receive dataset upgrades. However it is unlikely to receive performance improvements or new features.

Capture dates

2026-01-20T00:00:00-06:00

API responses now include capture date ranges!

GET https://api.gpxz.io/v1/elevation/point?lat=-43.624&lon=172.741

{
  "result": {
    "elevation": 53.061413,
    "lat": -43.624,
    "lon": 172.741,
    "data_source": "nz_1m_dtm",
    "resolution": 1,
    "capture_date_min": "2018-03-14",
    "capture_date_max": "2023-08-15"
  },
  "status": "OK"
}

Capture dates have been added to the following endpoints:

For more information, see the individual endpoint documentation, or read on.

The temporal dimension

Elevation data is typically collected by some sort of overhead survey: a drone, plane, or satellite is flown over an area with an elevation sensor pointed at the ground.

But ground elevation changes over time! Sometimes this change is human-driven: earthwork like mining or land reclamation. And sometimes the change is natural: subsidence, earthquakes, changing hydrology.

So knowing when the data acquisition was performed can be critical in understanding which terrain features will be captured in your elevation model.

This is what GPXZ now exposes for many API endpoints.

Date ranges

The image acquisition information is given as a range. Sometimes this is because the elevation at a given location was assimilated from multiple captures on multiple different dates. But usually it’s because it took months or years to run all the acquisition flights, and the granular data of which flight captured which exact area wasn’t published.

In cases where granular image acquisition data is provided, GPXZ is able to refine the capture date range. For example, the /v1/elevation/point query above returned data from the with a capture date range of 2018-03-14 to 2023-08-15 from the nz_1m_dtm source. But if we check the source information for nz_1m_dtm we can see the date range for the full dataset is much wider

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

// ...
{
  "data_source": "nz_1m_dtm",
  "name": "LINZ 1m Lidar",
  "resolution": 1,
  "url": "https://data.linz.govt.nz/layers/category/elevation/",
  "organization": "Land Information New Zealand",
  "attribution": "CC-BY-4.0: LINZ",
  "licence": "Creative Commons Attribution 4.0 International",
  "licence_url": "https://creativecommons.org/licenses/by/4.0/",
  "capture_date_min": "2008-05-01",
  "capture_date_max": "2024-06-28"
}
// ...

Incomplete ranges

Some elevation data sources don’t publish the date of image capture. In these cases, it’s still possible to determine an upper bound for the maximum date. The date of publication of the dataset is a good one if we are sure the data hasn’t been updated post-release. Otherwise the date we obtained the dataset is used as a conservative maximum date.

So the GPXZ API will always provide a valid date for the maximum capture date.

Unfortunately, there’s no such trick that can be used for the minimum capture date. Some (typically low-resolution) elevation datasets use contour information from printed maps, which can be super old! So you may see a null value for minimum capture date.

Unemboldening

2025-12-16T00:00:00-06:00

When I designed the GPXZ homepage in 2021, I made a whimsical decision to emphasise key words in bold.

I felt it provided a rough overview to someone who was quickly scanning the site.

It was also a nod to the MAD magazine comics I devoured as a kid.

But now, speckling prose with bold is a calling card of LLMs.

So the homepage bolding has been removed.

My company works because it has a reputation for quality and for excellent support (direct from the human that wrote the code and runs the business). The appearance of an LLM-generated homepage would undermine both of these characteristics.

Accessing GPXZ with python

2025-12-16T00:00:00-06:00

An overview of querying and analysing GPXZ elevation data using python.

Authentication

You’ll need an API key to use the GPXZ elevation API. This requirement cuts down on misuse and helps us make sure there’s enough server capacity for everyone. But it’s easy and free to make an account and it comes with lots of quota!

Once you’re signed up, you should see your API key displayed on the dashboard. It will be a bunch of random characters starting with ak_, for example: ak_k2g47_gd9ni6818xj6. We’ll use the key ak_demo_apikey in this guide to make it clear it’s not a live key.

The easiest way to authenticate queries is to use the key as a URL query argument. Basically, adding &api-key=ak_demo_apikey to the end of your URLs. This approach makes it easy to test queries in the browser. Try visiting the URL below, then replace ak_demo_apikey with your own API key:

api.gpxz.io/v1/elevation/point?lat=44.841&lon=-0.569&api-key=ak_demo_apikey

You should see a successful response, showing the elevation of the Miroir d’eau in Bordeaux, France as about 5 metres.

{
  "result": {
    "elevation": 5.134736,
    "lat": 44.841,
    "lon": -0.569,
    "data_source": "france_1m_dtm",
    "resolution": 1
  },
  "status": "OK"
}

Now you’re ready to start exploring elevation data with python!

One final note: while the URL-based API key is convenient for debugging, it’s recommended to eventually move to adding the key as an HTTP header instead. URLs have a tendency to be logged, displayed, and shared, which makes it harder to keep your API key a secret. HTTP headers don’t have these problems. We’ll cover header-based authentication with python shortly.

Querying the elevation for a single point

To query the elevation of a single point with the GPXZ API you’ll need a latitude and a longitude. If you’re doing this manually, you can fit the coordinates of a point by right-clicking it on Google Maps. For example, right-clicking the Sydney Opera House in Google Maps gives the coordinates -33.85777731669462, 151.2148714376462.

Some notes about latitude and longitude coordinates:

Most software will give coordinates in latitude,longitude order. But it’s still fairly common to represent coordinates the other way around, with longitude first! Make sure you check which order your data is in. Checking a location in Australia or California is one way to do this, as a latitude can’t be less than -90 or greater than 90.
GPXZ uses the common convention of longitudes being between -180 and 180. However, some software allows longitudes to “wrap” outside of this range. We’ll cover fixing this later in the guide.
Some software will give lots of decimal points for lat/lon coordinates. But unless you’re trying to locate individual atoms, this level of precision is unnecessary! The GPXZ dataset currently goes down to 50cm of resolution, where 7 decimal places of latitude and longitude is more than sufficient.

Now, lets finally get python to query this for us. We can use the /v1/elevation/point endpoint for this (here’s a list of all the GPXZ endpoints for reference).

# Import the libraries we need.
import requests

# Define the data.
#
# Remember to replace with your own API key!
gpxz_api_key = "ak_demo_apikey"
latitude = -33.857
longitude = 151.214
endpoint = "https://api.gpxz.io/v1/elevation/point"

# Set up the query.
#
# The data variables can be called whatever you like, 
# but the string keys (lat, lon, api_key) must match the API docs exactly.
params = {
    "lat": latitude,
    "lon": longitude,
    "api_key": gpxz_api_key,
}

# Make the request.
response = requests.get(
    endpoint,
    params=params,
)

# Convert the json text response into a python dictionary.
data = response.json()
print(data)

# {'result': {'elevation': 3.214107, 'lat': -33.857, 'lon': 151.214, 'data_source': 'australia_5m', 'resolution': 5}, 'status': 'OK'}

Pretty printing the result

The example above spits out everything on one line. This will get tricky to view as we move to more complex queries.

For slightly nicer formatting, we can use the builtin json library to view the response more neatly.

import json

print(json.dumps(data, indent=4))
# {
#     "result": {
#         "elevation": 3.214107,
#         "lat": -33.857,
#         "lon": 151.214,
#         "data_source": "australia_5m",
#         "resolution": 5
#     },
#     "status": "OK"
# }

Using the builtin urllib library

The examples in this guide all use the requests library. You can install it with the command pip install requests and it’s so common that it might already be installed in your environment!

But if you’d like to use the urllib library that comes preinstalled with python instead, you can modify the initial example like this

from urllib.parse import urlencode
from urllib.request import urlopen
import json

# Define the data and build the query parameters as before.
gpxz_api_key = "ak_demo_apikey"
latitude = -33.857
longitude = 151.214
endpoint = "https://api.gpxz.io/v1/elevation/point"
params = {
    "lat": latitude,
    "lon": longitude,
    "api_key": gpxz_api_key,
}

# With urllib we have to maually build the url.
query_string = urlencode(params)
url = endpoint + "?" + query_string

# Make the request and parse the response.
with urlopen(url) as response:
    data = json.load(response)

You have to do a little more work than with the requests library, but all the examples in this guide can be rewritten to work with urllib.

Validating the API response

It’s good practice to validate the HTTP status code of the response.

This is a number returned with API responses that will be 200 when successful, and something else if unsuccessful. The requests library has the raise_for_status() method that will throw an error for non-successful status codes. That prevents your code from continuing to operate on invalid data!

# Make the request and validate the response.
response = requests.get(
    endpoint,
    params=params,
)
response.raise_for_status()

Wrapping longitudes

GPXZ requires longitudes to be between -180 and 180. However you may come across different definitions: for example, the longitude 511.2 or -208.8 can sometimes represent Sydney’s longitude of 151.2. To convert to the ±180 format, keep adding/removing 360 from the value until it falls into the correct range.

def wrap_lon(lon: float) -> float:
    """Wrap longitude between -180 and 180."""
    while lon > 180:
        lon -= 360
    while lon < -180:
        lon += 360
    return lon

print(wrap_lon(511.2))
# 151.2

Including the API key as a header

It’s fine to place API keys in the URL when debugging, but if moving to production it’s better to transmit them in a header. GPXZ uses the x-api-key header for authentication.

The requests library makes this simple:

# Set up the query.
params = {
    "lat": latitude,
    "lon": longitude,
}
headers = {"x-api-key": gpxz_api_key}

# Make the request.
response = requests.get(
    endpoint,
    params=params,
    headers=headers,
)

Requesting the elevation of multiple points

GPXZ lets you query multiple points in a single query. A multi-point query still only counts as a single request against your quota, and is a lot faster than querying single points in a loop!

A multi-point request is also a natural way of querying multi-point data, like a route made up of multiple GPS location readings. And unlike the Google Maps Elevation API, GPXZ doesn’t reduce the accuracy of data queried in batches.

We’ll switch to the /v1/elevation/points endpoint for this.

GPXZ calls its coordinates parameter latlons to make it clear that the coordinates should be in latitude-then-longitude order.
Points should be separated by the pipe character |.

Here’s a browser example of a short segment along Abbey Road in London:

api.gpxz.io/v1/elevation/points?latlons=51.5317,-0.1770|51.5378,-0.1846|51.5398,-0.1872&api-key=ak_demo_apikey

And here’s that same example in python:

import json
import requests

# Define the data.
gpxz_api_key = "ak_demo_apikey"
endpoint = "https://api.gpxz.io/v1/elevation/points"
latlon_coords = [
    (51.5317, -0.1770),
    (51.5378, -0.1846),
    (51.5398, -0.1872), 
]

# Build the query.
#
# Coords are separated by ',' points by '|'.
latlon_string = ""
for point in latlon_coords:
    latlon_string += str(point[0])
    latlon_string += ","
    latlon_string += str(point[1])
    latlon_string += "|"
latlon_string = latlon_string.rstrip("|")
params = {"latlons": latlon_string}
headers = {"x-api-key": gpxz_api_key}

# Make the request.
response = requests.get(
    endpoint,
    params=params,
    headers=headers,
)
response.raise_for_status()

# View the result.
data = response.json()
print(json.dumps(data, indent=4))

# {
#     "results": [
#         {
#             "elevation": 43.950146,
#             "lat": 51.5317,
#             "lon": -0.177,
#             "data_source": "england_2022_1m_dtm",
#             "resolution": 1
#         },
#         {
#             "elevation": 35.387238,
#             "lat": 51.5378,
#             "lon": -0.1846,
#             "data_source": "england_2022_1m_dtm",
#             "resolution": 1
#         },
#         {
#             "elevation": 37.162411,
#             "lat": 51.5398,
#             "lon": -0.1872,
#             "data_source": "england_2022_1m_dtm",
#             "resolution": 1
#         }
#     ],
#     "status": "OK"
# }

With the result as a dictionary, you can extract the information you need. For example, to pull out a list of elevations:

elevations = [result["elevation"] for result in data["results"]]

Requesting a single point with the multi-point endpoint

The /v1/elevation/points endpoint does accept a single point! Just use latlons=51.5398,-0.1872 instead of lat=51.5398&lon=-0.1872, and keep in mind you’ll still get a list of results (with a single result element!)

Batching points

The points endpoint is limited to 512 points per request. If you have more points than that (or need to handle user-generated point collections that may be larger than that), you’ll need to split your points into multiple batches of 512.

gpxz_batch_size = 512

import random

import requests

# For this example, randomly generate coordinates.
n_points = 2000
gpxz_batch_size = 512
lats = [random.uniform(-90, 90) for _ in range(n_points)]
lons = [random.uniform(-180, 180) for _ in range(n_points)]
latlons = zip(lats, lons)

# Simple function to split a list into batches.
def batch_list(items: list, batch_size: int) -> list[list]:
    batches = []
    index = 0
    while index < len(items):
        batch = items[index: index + batch_size]
        batches.append(batch)
        index += batch_size

    return batches

# Make the batch requests.
# 
# Merge all the result objects into one list.
results = []
headers = {"x-api-key": gpxz_api_key}
for latlon_batch in batch_list(latlons):
    latlon_string = "|".join(",".join(map(str, x)) for x in latlon_batch)
    params = {"latlons": latlon_string}
    response = requests.get(
        endpoint,
        params=params,
        headers=headers,
    )
    response.raise_for_status()
    results += response.json()["results"]

If you have numpy installed, the array_split function saves you having to write your own:

import numpy as np

...
n_batches = np.ceil(len(latlons) / gpxz_batch_size)
latlon_batches = np.array_split(latlons, n_batches)

POST requests

Stuffing all these coordinates in a query argument can result in some rather large URLs, especially if you’re adding lots of decimal places!

The GPXZ can accept rather large URLs (up to about 60,000 characters long!) but not all software is so forgiving. Any browser, HTTP request library, or proxy you’re using may impose a lower limit.

To avoid such issues, the /v1/elevation/points endpoint also supports POST requests. Simply convert any query arguments to POST data instead:

import requests

gpxz_api_key = "ak_demo_apikey"
endpoint = "https://api.gpxz.io/v1/elevation/points"
latlon_string = "51.5317,-0.177|51.5378,-0.1846|51.5398,-0.1872"

params = {"latlons": latlon_string}
headers = {"x-api-key": gpxz_api_key}

response = requests.post(
    endpoint,
    data=params,
    headers=headers,
)
response.raise_for_status()
data = response.json()

Polyline requests

You can also convert your coordinates to a polyline string.

import polyline
import requests

# Data setup.
gpxz_api_key = "ak_demo_apikey"
endpoint = "https://api.gpxz.io/v1/elevation/points"
latlon_coords = [
    (51.5317, -0.1770),
    (51.5378, -0.1846),
    (51.5398, -0.1872), 
]

# Build the polyline.
#
# Increase precision above the default 5 for hires elevation data.
polyline_string = polyline.encode(latlon_coords, precision=6)

# Make the request using the `polyline` arg rather than the `latlons` one.
params = {"polyline": polyline_string}
headers = {"x-api-key": gpxz_api_key}
response = requests.get(
    endpoint,
    params=params,
    headers=headers,
)
response.raise_for_status()
data = response.json()

Migrating from the Google Maps Elevation API

Migrating from Google Maps to GPXZ is easy! Simply replace https://maps.googleapis.com/maps/api/elevation with https://api.gpxz.io/v1/elevation/gmaps-compat and update your API key.

Take this example from Air Sciences Inc., which is loading a shapefile and adding elevation data to it.

import matplotlib.pyplot as plt
import geopandas as gpd
import requests
from shapely.geometry import Point
from os.path import join as pth_join
import json
import time

#Configure API request link
url_root = "https://maps.googleapis.com/maps/api/elevation"
key_str = "GFVerAfCoyBsdfPD7nnW8QQC7ZZt5ytKiCO4e3Zu"
output_fmt = "json"
request_str = "%s/%s?locations=%s&key=%s"

#Define data inputs and outputs
data_root = "/Users/airsci/git/wrap-cmfd/CM_data"
input_file = "wrap_oregon_odf_clean.shp"
output_file = input_file[:-4]+"_elev.shp"

#Read input file into a GeoDataFrame
gdf = gpd.read_file(pth_join(data_root,input_file))
gdf_wgs = gdf.to_crs("EPSG:4326")

#Extract x,y from geometry and convert to strings
build_str = gdf_wgs['geometry'].apply(lambda v: ("%s,%s|" % (str(v.y), str(v.x))))

#Build concatenated string for API request
locs = "".join([x for x in build_str]).rstrip('|')

#Make request, parse results
r = requests.get(request_str % (url_root, output_fmt, locs, key_str))
parsed = json.loads(r.text)

#Extract elevations from result
geom = [Point(
    i['location']['lng'], i['location']['lat'],
    i['elevation']) for i in parsed['results'],
]

Without changing any of the complex geospatial and data wrangling logic, you can migrate to GPXZ’s high-quality elevation data by changing just the API key end endpoint:

url_root = "https://api.gpxz.io/v1/elevation/gmaps-compat"
key_str = "ak_demo_apikey"  # GPXZ API key.

Everything else about the parsing will remain the same: the same input parameters, and the same output format.

Migrating from opentopodata

It’s also easy to migrate from opentopodata: perhaps you’re running into rate-limiting or CORS restrictions on opentopodata, or just need higher quality and resolution elevation data.

Again, just replace the endpoint (/v1/elevation/otd-compat/<dataset>) with the GPXZ equivalent https://api.gpxz.io/v1/elevation/otd-compat, and add you API key.

Because GPXZ uses the best sources available at all locations, there’s no need to specify your dataset like with opentopodata. So for example, if you’re using the mapzen dataset with /v1/elevation/otd-compat/mapzen you would still use https://api.gpxz.io/v1/elevation/otd-compat.

Querying source info

Every response from the GPXZ API for elevation data includes a data_source attribute, which indicates the provenance of the elevation data used.

The data_source value is a short human-readable ID. To get the full information about that source, you can query the /v1/elevation/sources endpoint.

import requests
import json

gpxz_api_key = "ak_demo_apikey"
headers = {"x-api-key": gpxz_api_key}

# Define some different points around the world.
latlon_coords = [
    (-43.508, 172.633),
    (22.395, 114.165),
    (51.915, 5.380), 
]
latlon_string = "|".join(",".join(map(str, x)) for x in latlon_coords)
params = {"latlons": latlon_string}

# Query elevation, saving the results as a list of results.
response_elevation = requests.get(
    "https://api.gpxz.io/v1/elevation/points",
    params=params,
    headers=headers,
)
response_elevation.raise_for_status()
data_elevation = response_elevation.json()
results = data_elevation["results"]

# Also query the source info.
#
# Convert the result list into a dict for easy lookups.
response_sources = requests.get(
    "https://api.gpxz.io/v1/elevation/sources",
    headers=headers,
)
response_sources.raise_for_status()
data_sources = response_sources.json()
source_infos = {x["data_source"]: x for x in data_sources["results"]}

# Modify the elevation results, adding the respective source information.
for result in results:
    result["source_info"] = source_infos[result["data_source"]]

# Pretty print the result.
print(json.dumps(results, indent=4))
# [
#     {
#         "elevation": 8.153094,
#         "lat": -43.508,
#         "lon": 172.633,
#         "data_source": "nz_1m_dtm",
#         "resolution": 1,
#         "source_info": {
#             "data_source": "nz_1m_dtm",
#             "name": "LINZ 1m Lidar",
#             "resolution": 1,
#             "url": "https://data.linz.govt.nz/layers/category/elevation/",
#             "organization": "Land Information New Zealand",
#             "attribution": "CC-BY-4.0: LINZ",
#             "licence": "Creative Commons Attribution 4.0 International",
#             "licence_url": "https://creativecommons.org/licenses/by/4.0/",
#             "capture_date_min": "2020-01-01",
#             "capture_date_max": "2022-12-31"
#         }
#     },
#     {
#         "elevation": 314.017609,
#         "lat": 22.395,
#         "lon": 114.165,
#         "data_source": "hong_kong_50cm_dtm",
#         "resolution": 0.5,
#         "source_info": {
#             "data_source": "hong_kong_50cm_dtm",
#             "name": "Hong Kong 50cm DTM 2020",
#             "resolution": 0.5,
#             "url": "https://geodata.gov.hk/gs/view-dataset?uuid=cb6c4d1e-fc38-46cc-974a-77253a773592&sidx=0",
#             "organization": "Hong Kong Civil Engineering and Development Department",
#             "attribution": "Hong Kong Geodata Store",
#             "licence": "Hong Kong Geodata Store Terms",
#             "licence_url": "https://geodata.gov.hk/gs/?p=terms_and_conditions",
#             "capture_date_min": "2008-05-01",
#             "capture_date_max": "2024-06-28"
#         }
#     },
#     {
#         "elevation": 3.762188,
#         "lat": 51.915,
#         "lon": 5.38,
#         "data_source": "netherlands_50cm_dtm",
#         "resolution": 2,
#         "source_info": {
#             "data_source": "netherlands_50cm_dtm",
#             "name": "Netherlands 50cm AHN4 DTM",
#             "resolution": 2,
#             "url": "https://www.ahn.nl/ahn-4",
#             "organization": "Actueel Hoogtebestand Nederland",
#             "attribution": "CC0",
#             "licence": "CC0 1.0 Universal",
#             "licence_url": "https://creativecommons.org/publicdomain/zero/1.0/",
#             "capture_date_min": "2020-01-01",
#             "capture_date_max": "2022-12-31"
#         }
#     }
# ]

Querying rasters

As well as points, the GPXZ API also lets you query 2D rasters with the /v1/elevation/raster endpoint.

You always need to define the rectangular bounding box of your raster, it can be any size. Then you’ll also need to specify the resolution of your raster. This can be done in metres:

import requests

# Define the bounding box.
lat_min = -36.879
lat_max = -36.871
lon_min = 174.761
lon_max = 174.768
params = {
    "bbox_left": lon_min,
    "bbox_right": lon_max,
    "bbox_bottom": lat_min,
    "bbox_top": lat_max,
    "resolution_m": 2,
}

# And where we want to save the output file.
output_path = "/tmp/gpxz-demo-raster.tif"

# Otherwise make the request as usual.
gpxz_api_key = "ak_demo_apikey"
headers = {"x-api-key": gpxz_api_key}
response = requests.get(
    "https://api.gpxz.io/v1/elevation/raster",
    params=params,
    headers=headers,
)
response.raise_for_status()

# Then save the raster.
with open(output_path, "wb") as f:
    f.write(response.content)

but you can also specify the resolution in the raster projection (for example, degrees):

import requests

# Get a raster of the whole globe.
lat_min = -90
lat_max = 90
lon_min = -180
lon_max = 180
params = {
    "bbox_left": lon_min,
    "bbox_right": lon_max,
    "bbox_bottom": lat_min,
    "bbox_top": lat_max,
    "resolution_x": 0.5,
    "resolution_y": 0.5,
    "projection": "epsg:4326",
}

output_path = "/tmp/gpxz-demo-raster.tif"
gpxz_api_key = "ak_demo_apikey"
headers = {"x-api-key": gpxz_api_key}
response = requests.get(
    "https://api.gpxz.io/v1/elevation/raster",
    params=params,
    headers=headers,
)

or specify the shape (in pixels) of the output raster:

import requests

# Get a raster of the whole globe.
lat_min = -90
lat_max = 90
lon_min = -180
lon_max = 180
params = {
    "bbox_left": lon_min,
    "bbox_right": lon_max,
    "bbox_bottom": lat_min,
    "bbox_top": lat_max,
    "height_px": 180,
    "width_px": 360,
}

output_path = "/tmp/gpxz-demo-raster.tif"
gpxz_api_key = "ak_demo_apikey"
headers = {"x-api-key": gpxz_api_key}
response = requests.get(
    "https://api.gpxz.io/v1/elevation/raster",
    params=params,
    headers=headers,
)

There are more options for working with bathymetry, different projections, and geotiff compatability. Check out the raster endpoint documentation for the more.

Streaming rasters to disk

The above approach will load the entire raster into memory, then write it to disk once the HTTP request has completed. To reduce memory impact for large rasters, you can instead stream the response to disk (writing the file directly to disk):

import requests
import shutil

...

 with requests.get(url, stream=True) as r:
    with open(output_path, "wb") as f:
        shutil.copyfileobj(r.raw, f)

Loading rasters directly with rasterio

If using the amazingly-helpful rasterio library, it can download rasters directly. The only catch is you’ll have to put all the request parameters (including your API key) into the URL.

from urllib.parse import urlencode

import rasterio

# Built the url.
endpoint = "https://api.gpxz.io/v1/elevation/hires-raster"
gpxz_api_key = "ak_demo_apikey"
params = {
    "bbox_left": lon_min,
    "bbox_right": lon_max,
    "bbox_bottom": lat_min,
    "bbox_top": lat_max,
    "api_key": gpxz_api_key,
}
query_string = urlencode(params)
url = endpoint + "?" + query_string

# Rasterio is smart enough to read URLs directly. GDAL may need prefixing
# with the "magic" file system token `/vsicurl/`
with rasterio.open(url) as f:
    z_array = f.read(1)

Extracting the highest-quality rasters

GPXZ has a second raster endpoing /v1/elevation/raw-raster that extracts rasters from the GPXZ dataset with minimal reprojection, interpolation, and transformation. The result is a higher quality output in many cases! But the output rasters will be in a wide range of projections and resolutions.

Simply specify the bounding box.

import requests

# Define the bounding box.
lat_min = -36.879
lat_max = -36.871
lon_min = 174.761
lon_max = 174.768
params = {
    "bbox_left": lon_min,
    "bbox_right": lon_max,
    "bbox_bottom": lat_min,
    "bbox_top": lat_max,
}

# And where we want to save the output file.
output_path = "/tmp/gpxz-demo-raster.tif"

# Otherwise make the request as usual.
gpxz_api_key = "ak_demo_apikey"
headers = {"x-api-key": gpxz_api_key}
response = requests.get(
    "https://api.gpxz.io/v1/elevation/raw-raster",
    params=params,
    headers=headers,
)
response.raise_for_status()

# Then save the raster.
with open(output_path, "wb") as f:
    f.write(response.content)

Upcoming GPXZ dataset update (v2025.1)

2025-12-03T00:00:00-06:00

The GPXZ elevation dataset will be upgraded next week!

The API will return data from the new dataset beginning 2025-12-10 23:59 UTC.

Most users need to do nothing: new queries will soon start to return improved data. Some users may want to rebuild processed data or re-fetch cached queries.

The main changes are

New areas of hires coverage in Europe.
Expanded hires coverage in many areas, including USA, NZ, and Canada.
Tree and building removal in our non-lidar global basemap.
Vertical datum normalisation.

API changes

Once the new dataset is live, API responses will have the value 2025.1 in the X-DATASET-VERSION header.

The source attribute that’s included in most API responses may contain some new values. These new source ids will be added to the /v1/elevation/sources endpoint.

Coverage changes

The latest dataset adds many new areas of high resolution lidar data, as well as updated data for existing areas of hires coverage.

New hi-res coverage

Norway (whole country at a 1m resolution)
Estonia (whole country at 1m)
Netherlands (whole country at 50cm)
Belgium (whole country at 20m, Brussels and Flanders at 1m)
Germany (most states at 1m)

Improved hi-res coverage

New Zealand (expanded coverage: most of the country including all major population centres are now covered)
USA
- The 10m base coverage for the USA has been updated.
- Expanded 1m lidar coverage, now covering the majority of the country.
Canada (expanded 1m lidar coverage, particularly in Quebec and Ontario).
GEBCO (wordwide) and EMOD (Europe) bathymetry have been updated to their latest versions.
England (updated to the latest version)
France (filled some areas of missing data for full country coverage)

Methodology changes

Global terrain basemap

v2025.1 uses a new gobal basemap for areas without lidar coverage. We used a variety of data sources and satistical methods to reduce the tree and building bias in the 30m Copernicus surface dataset. As a result, the GPXZ elevation dataset is now a global terrain model.

Updated merge algorithm

The source merging algorithm for v2025.1 uses the same philosopy as previous version, but has been rewritten to produce smoother merges and better correct erroneous data.

Notable areas of improvement include

Smoother land-bathymetry mergeing.
Smoother merging between datasets.
Expaned QA process identifying and resolving more errors contained in source DEMs.

Vertical datum normalisation

All elevation values are now given relative to EGM2008 (EPSG:3855).

EU region

2025-04-21T00:00:00-05:00

The GPXZ API now has an EU region!

Use the new api-eu.gpxz.io domain to ensure your elevation queries are performed on servers located within the EU.

Check out the EU region documentation for details.

Raster output profiles

2025-03-31T00:00:00-05:00

The GPXZ raster API lets you extract high-resolution raster DEMs for a given bounding box. The output is provided as a GeoTIFF.

While GeoTIFF is a standard format, it’s also a rather complex one that’s still being updated today. As a result, not all tools support all GeoTIFF files.

We just added a output_profile parameter that lets customers specify a compatibility profile for the GeoTIFF’s returned by the /v1/elevation/hires-raster endpoint. Currently three profiles are supported

zstd uses the Zstandard GeoTIFF compression setting. GeoTIFFs compresses with Zstandard result in some of the smallest filesizes and fastest read times of any compression algorithm. It’s also by far the fastest compression option to write, resulting in faster response times from the GPXZ API. The only downsize is that older tooling doesn’t always support Zstandard.
autocad enables a number of compatibility features required to import GeoTIFFs into Autodesk products such as AutoCAD. One of those options however is that rasters are limited to 4GB in size; the GPXZ API will return a 400 status code in if a 4GB+ raster is requested with the autocad profile.
default is, well, our default raster profile. It’s what we’ve been using since the launch of the API. It produces a cloud-optimised GeoTIFF that is compatible with most tools while still making use of reasonable compression levels and file sizes.

If you’re having compatibility issues with your tooling, please get in touch and we might be able to add a new profile.

Validating rasters

2025-03-28T00:00:00-05:00

GPXZ stores over 10 million unique GeoTIFF rasters between our dataset and our sources. The number of actual files is much larger as those rasters are duplicated many times across our infrastructure.

When shepherding so many files, it’s inevitable to come across some invalid ones. Sometimes the file comes with errors already from the source. Other times files develop corruption, due to software bugs or hardware crashes.

While the final GPXZ dataset goes through a robust QA process to ensure invalid data never reaches our customers, it’s still much easier to resolve data corruption that’s detected as soon as it occurs.

At GPXZ we run a validate-rasters script which we run on any files that have been downloaded, written to, or copied. If you’re interested in building a similar tool, some approaches are outlined below.

gdalinfo

The gdalinfo command gives information about a raster file.

gdalinfo S48E167.tif

# Driver: GTiff/GeoTIFF
# Files: S48E167.tif
# [there's lots more lines which I've truncated here]

If you pass a file that isn’t a geospatial raster then you get an error message

gdalinfo gpxz_logo.tif

# ERROR 4: `gpxz_logo.png' not recognized as being in a supported file format.
# gdalinfo failed - unable to open 'gpxz_logo.png'.

and more importantly you get a non-zero status code which will be interpreted as an error (e.g., if calling from python this will throw a python exception, or if chaining commands with &&)

echo $?  # Display the most recent status code.

# 1

Because we don’t really care about the actual output for validation purposes, we can add a few flags that reduce verbosity

gdalinfo -nomd -norat -noct -nomask S48E167.tif

Used like this, gdalinfo will catch major problems like zero-length files. But because many formats (most notable GeoTIFF) encode all this metadata at the start of the file, simply running gdalinfo won’t catch files that have been corrupted by a crash during writing, which in our experience is one of the most common causes of corruption.

If we truncate a valid GeoTIFF and check it

head -c 100000 S48E167.tif > S48E167.truncated.tif
gdalinfo S48E167.truncated.tif

# Driver: GTiff/GeoTIFF
# Files: S48E167.truncated.tif
# ...

gdal will happily rattle of the metadata from the header and exit with a successful return code!

gdalinfo -stats

To be assured that your data is good, there’s no option but to read it all. Luckily we can again [mis]use gdalinfo to do this by asking it to compute the summary statistics of our data with the -stats flag.

gdalinfo -stats S48E167.tif

# Driver: GTiff/GeoTIFF
# Files: S48E167.tif
# ...
#   Metadata:
#     STATISTICS_MINIMUM=-15
#     STATISTICS_MAXIMUM=746
#     STATISTICS_MEAN=17.086878887742
#     STATISTICS_STDDEV=67.97198232226
#     STATISTICS_VALID_PERCENT=100

At the end of our output we now have some summary statistics which require reading every pixel of the raster to compute. Repeating the command on our corrupted raster gives the error we’re expecting

gdalinfo -stats S48E167.truncated.tif

# ERROR 1: TIFFFillStrip:Read error at scanline 99; got 0 bytes, expected 678
# ERROR 1: TIFFReadEncodedStrip() failed.
# ERROR 1: S48E167.truncated.tif, band 1: IReadBlock failed at X offset 0, Y offset 100: TIFFReadEncodedStrip() failed.
# Driver: GTiff/GeoTIFF
# Files: S48E167.truncated.tif
# ...

echo $?

# 130

rasterio

The gdalinfo -stats command requires reading (and decompressing) the entire raster. If you’re willing you go through all that effort anyway, there’s even more categories of invalid rasters that can be detected! We’ll need to switch over to a more expressive programming language though.

Start by reading the data into memory. This step is enough to catch all the cases covered by gdalinfo -stats, though it will crash on larger-than-memory files.

with rasterio.open(raster_path) as f:
    a = f.read(masked=True)
    meta = f.meta

Now we can add extra test cases.

Like checking if our GeoTIFF file is actually a GeoTIFF, not something else with a .tif filename extension

assert meta["driver"] == "GTiff"

and checking for common NODATA values that don’t represent actual data.

a_filled = np.ma.filled(a, np.nan)
assert not np.any(a_filled == -32768)
assert not np.any(a_filled == -9999)

Domain-specific checks can be added too that go beyond file integrity into data integrity.

For (earth-based) DEMs (in metres) we know the range of expected values

assert np.nanmax(a_filled) < ELEVATION_MT_EVEREST
assert ELEVATION_MARIANA_TRENCH < np.nanmin(a_filled)

and are expecting only a single channel

assert meta['count'] == 1

Elevation

GPXZ is an API for elevation data. Access the highest-quality DEMs globally with a free account.

We also do consulting work around DEMs and geospatial data management. If that sounds like something you could use, reach out at support@gpxz.io!