gpxz

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.

You’ll need to define the rectangular bounding box of your raster, which must be less than 10km2.

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/hires-raster",
    params=params,
    headers=headers,
)
response.raise_for_status()

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

The resulting raster will be in a UTM projection, with a 1m resolution. Check out the raster endpoint documentation for the many different options to configure your output raster.

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 raster

# 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)

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!

Extracting DEMs from a WCS server

2025-03-27T00:00:00-05:00

WCS is an interface for retrieving geospatial data. It integrates well with specialised GIS tools like QGIS, but there’s not a lot of information out there about using WCS with custom analytical workflows. So here’s an overview of how you would extract raster DEM data from a WCS server in Python.

It’s worth noting that while WCS is a standard, it mostly specifies how client-server communication is done rather that the schema of the data. Which means that each WCS server may need slightly different handling.

Summary

The basic WCS flow is

Connect to the WCS server
Determine the “coverage ID” representing the desired data
Determine the extent and projection of the data
Split the extent into tiles
Query each tile

Steps

You’ll need OWSLib installed to handle the WCS protocol

pip install OWSLib

as well as some standard python tools which may be installed already

pip install numpy requests

Start off by connecting to the WCS server, which is defined by a URL

from owslib.wcs import WebCoverageService

WCS_URL = "https://example./com/ows/wcs"
wcs = WebCoverageService(WCS_URL)

WCS has a concept of “coverages”, which are analogous to a layer or a dataset. List all the server’s coverages with

wcs.contents.keys()

['example_dem']

and select the one you want

coverage_id = "example_dem"
coverage = wcs.contents[coverage_id]

The next piece of information we need is the spatial extent of the data.

coverage.boundingBox

{
    'nativeSrs': 'http://www.opengis.net/def/crs/EPSG/0/25833',
    'bbox': (228152.0, 5690412.0, 493382.0, 5939023.0)
}

We get a bounding box (in west, south, east, north) order, and a CRS definition. Note how the CRS for this server is specified using a URL rather than an EPSG code or WKT string. If you’re providing your own bounding box (to extract only a subset of the full coverage) make sure it is in the correct CRS.

I find it easy to mess up these unnamed bounding box tuples, so always unpack them instead,

bounds_left, bounds_bottom, bounds_right, bounds_top = coverage.boundingBox['bbox']

For small domains, you can likely query the entire dataset in one go. But for large domains such as this, you’ll need to split up your query into tiles. Choosing the correct tile size will take a bit of guess and check: some servers impose per-query size limits, while others may simply timeout before any limit is reached.

We’ll also define a buffer so that our tiles overlap. This helps avoiding holes, and preserves accuracy when making interpolated raster reads near the edges.

The tile sizes should be in the units of the nativeSrs of the coverage, and should be integer multiples of the dataset’s resolution.

tile_size = 10000
tile_buffer = 10

Now some numpy magic to define the lower-left corners of our tile grids.

import numpy as np

lefts = np.arange(
    bounds_left - bounds_left % tile_size, bounds_right - bounds_right % tile_size, tile_size
)

bottoms = np.arange(
    bounds_bottom - bounds_bottom % tile_size, bounds_top - bounds_top % tile_size, tile_size
)

We can do a nested loop over these corners and request each raster.

Some things to note:

While the query bounds are specified with the “Lat” and “Long” arguments, the query is actually being done in the CRS specified in subsettingcrs, even if that CRS isn’t latlon. In other words, think of Lat as y and Lon as x.
To avoid loss of accuracy via repeated reprojection and interpolation, do all the bounds calculation and subsetting the nativeSrs. You can always postprocess after exporting the data.
The file is named from the tile left/bottom coordinates for tidiness, though the actual extent of the tile will be buffered slightly larger.
The code streams the response to disk to avoid storing the potentially large file in memory.

from pathlib import Path
import itertools
import urllib.parse
import shutil

import requests


BASE_FOLDER = "~/wcs-extract-tifs/"
BASE_FOLDER.mkdir()


for left, bottom in itertools.product(lefts, bottoms):
    # Where to save the tile.
    tif_filename = f"dem_{left}_{bottom}.tif"
    tif_path = BASE_FOLDER / tif_filename

    # Tile query definition.
    params = [
        ("service", "WCS"),
        ("version", wcs.version),
        ("request", "GetCoverage"),
        ("coverageId", coverage_id),
        ("format", "image/tiff"),
        ("subset", f"Lat({bottom-tile_buffer},{bottom+tile_size+tile_buffer})"),
        ("subset", f"Long({left-tile_buffer},{left+tile_size+tile_buffer})"),
        ("subsettingcrs", "http://www.opengis.net/def/crs/EPSG/0/25833"),
    ]
    tile_url = WCS_URL + "?" + urllib.parse.urlencode(params)

    # Make query.
    with requests.get(tile_url, stream=True, timeout=60, verify=False) as r:
        r.raise_for_status()
        with open(tif_path, "wb") as f:
            shutil.copyfileobj(r.raw, f)

At this point your BASE_FOLDER should be full of .tif DEMs!

As a final optimisation, I find WCS servers typically do a bad job of compressing tifs. I’d recommend repacking each tif into a compressed COG geotiff with gdal_translate.

Elevation data

Stuck downloading DEMs from a WCS server? We might already have the data you’re looking for in our dataset, check out our coverage map.

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!

Turning a notebook into production code

2025-01-08T00:00:00-06:00

At GPXZ we make heavy use of jupyter notebooks for developing new features and adjusting existing algorithms. We love the rich output, easy inspection and tweaking of variables, and the ability to experiment on data without reloading it every time.

Once we’re happy with the result, here’s the steps we take to get that new logic into production.

1. Rerun from scratch

Jupyter lets you execute cells out of order: this is great for quick edits to your code without running everything. But it makes it east to accidentally get your notebook into an unrepeatable state.

So first ensure your notebook is correctly capturing the desired result:

Copy the notebook
Clear all outputs
Rerun all cells
Ensure the notebook completes without error
Ensure the results match the old notebook!

2. Extract utility functions

Most data science processes consist of “utility” functions where

You don’t care about intermediate state
The implementation isn’t core to your algorithm
Inputs and outputs are clearly defined and delineated

Our next step is to take these utility functions

# forecast_flowrate.ipynb

df["rainfall"] = float(df.weather_report.str.split("|").str[2]) / 25.4

and put them into their own file. Call it {notebook_name}_utils.py for now: though some utils might be more at home elsewhere in your codebase, and others might get moved back next to the core algorithm.

# forecast_flowrate_utils.py

MM_PER_INCH = 25.4

def extract_rainfall(weather_report: pd.Series) -> pd.Series:
    """Extract the rainfall part of a weather report.

    Reports look like "STATION_NAME|windspeed|rainfall" and are in imperial units.
    """
    weather_report_parts = weather_report.str.split("|")
    rainfall_str = weather_report_parts.str[2]
    rainfall_inches = float(rainfall_str)
    rainfall_mm = rainfall_inches * MM_PER_INCH
    return rainfall_mm

With our utility function extracted, it can be better documented and tested.

Importing the new module with autoreload will re-import the module in the notebook whenever the python file is changed

# forecast_flowrate.ipynb

%load_ext autoreload
%autoreload 2

import forecast_flowrate_utils

and our notebook logic is much easier to read with this computation busywork outsourced

# forecast_flowrate.ipynb

df["rainfall"] = forecast_flowrate_utils.extract_rainfall(df.weather_report)

Depending on your package layout, you may have to hack sys.path to import the utils module

# forecast_flowrate.ipynb

import sys

sys.path.append('forecaster/weather')

3. Extract model inputs and outputs

Our notebook forecast_flowrate.ipynb is going to become a function forecast_flowrate().

# Inputs.
START_AT = datetime.now(timezone.utc)
BOUNDING_BOX = None  # Use whole domain as default.

Having them in one place helps contextualize the model, makes them easy to modify for testing your notebook generalises to the entire input domain.

Extracting inputs may also help with building a repeatable model, though for data-heavy models this may require more work at the data layer.

Similarly, if the model result is currently only being displayed as a notebook cell output, make sure to either save the result or put a final cell of explicit outputs:

# Outputs.
FORECAST_TIMESERIES = df_result.flowrate.fillna(0).to_numpy()

4. Hoist constants

The constants in our models are often set based on lots of experimentation and research: this hard work may be lost without documentation of why the final value was chosen!

Move them to just under the imports of your notebook. Any number other than 0 or 1 should be scrutinised as a potential algorithm parameter.

# Standard deviation of DEM gaussian blur, in px.
#
# Smoothing is needed as our DEMs have a lot of single-pixel noise. But at a 30m resolution, excess
# smoothing removes small waterways, resulting in over-estimates for inundation. A value of 2 had
# the best cross-validation results over the domains in our initial launch, though may need tweaking
# if we move to a new DEM source. 
#
# The code for running the cross-validation is in explore/dem-sigma-cv.ipynb
DEM_SMOOTHING_SIGMA = 2

In production the logic of an algorithm, is largely fixed: desired outcomes are mostly achieved by modifying these constants, which is easier when they’re all clearly in one place/

It’s also easy in a notebook to hardcode these values during experimentation, even when it’s important for the value to be consistent across the notebook. Moving them to a constant variable enforces consistency.

dem = smooth_dem(load_dem(), sigma=2)
if np.any(np.isnan(dem)):
    dem = smooth_dem(load_backup_dem(), sigma=2.5)
    # Is sigma=2.5 because the backup dem needs more smoothing?
    # Or were we experimenting with higher smoothing and forgot to revert everywhere?

5. Add logging

One benefit of notebooks is that we can easily display intermediary results. Unlike more traditional development, where often code either runs or doesn’t, intermediary state can be critical for understanding the quality of a data-heavy simulation is heading.

The easiest way to capture this is to log any parameter that might possibly be important. Having your log messages look like unique_snake_case_name=result makes them easy to search using commandline tools like grep, and makes it possible to parse them for analysis if needed.

dem = load_dem()
logger.info(f"Loaded dem dem_nan_px={np.isinan(dem).sum()}")

More advanced is to use structured logging. Plots can be saved as PDFs.

And more ugly (but something we do frequently for GPXZ!) is to pass around a meta dict, save as much info as possible, and write it out as a single json file at the end of the run.

meta: dict[str, Any] = {}

dem = load_dem()
meta["dem_nan_px"] = np.isinan(dem).sum()

If you are stuffing a bunch of debugging info into a dict it’s likely to include stuff that can’t be serialilsed as json. We use a jsonify function a bit like this to handle that:

def jsonify(x):
    # Mapping.
    if isinstance(x, dict):
        return {k: jsonify(v) for k, v in x.items()}

    # Iterable.
    if isinstance(x, tuple | list):
        return [jsonify(v) for v in x]

    # Scalar.
    return _convert_json_value(x)

def _convert_json_value(v):
    """Convert values to json serialisable one."""
    if isinstance(v, np.ndarray):
        return [_convert_json_value(x) for x in v.tolist()]
    try:
        if math.isnan(v) or np.isnan(v):
            return None
    except TypeError:
        pass
    if isinstance(v, np.integer):
        return int(v)
    if isinstance(v, np.floating):
        return float(v)
    if isinstance(v, np.bool_):
        return bool(v)
    if isinstance(v, Path):
        return v.as_posix()
    if isinstance(v, datetime):
        return v.isoformat()
    if isinstance(v, Decimal):
        return float(v)
    return v

6. Abstraction

Ok now we’re ready to actually turn our notebook into a python file!

Your toplevel function should be a handful of functions that describe the model in high level:

DEM_SMOOTHING_SIGMA = 2

def forecast_flow_rate(start_at: datetime, domain: None | BoundingBox = None):
    """Single day ML forecast for flow at a streamgage location."""
    # Inputs.
    historic_flow = load_historic_flow(start_at)
    dem = load_dem(domain)
    precip = load_precipitation_forecast(domain, start_at)

    # Run model.
    forecast_result = run_lstm_flow_simulation(dem, precip, start_at)
    validate_forecast(forecast_result)

    # Save result.
    save_result_to_db(forecast_result)

Then copy each line of notebook code into the relevant sub function. Teasing out interactions between model steps is an excellent exercise for making sure you captured all your algorithm parameters, and weren’t relying on any weird notebook functionality.

Run unit tests, run model, compare to notebook output, done.

Vancouver Island 1m DEMs have some big holes

2024-11-11T00:00:00-06:00

The Canadian HRDEM dataset is made up of a number of different projects, each consisting of 1m or 2m lidar DEMs of different parts of Canada.

The project covering parts of Vancouver Island, named Vancouver_Island_Sunshine_Coast_2018, has a few rasters with corrupt data. Typically this is manifested in blocky areas with very low elevation, though there are a few areas with very high elevation.

Visualising the data, the corrupt areas are very clear. Here’s a heatmap of dtm_1m_utm10_w_5_136:

Looking at a hillshaded render, it seems there is some realistic texturing inside the corrupt region, but with both an incorrect vertical shift and diagonal striped artefacts:

These are the files with potential corruption:

dtm_1m_utm10_w_10_137.tif  dtm_1m_utm10_w_10_138.tif  dtm_1m_utm10_w_10_146.tif  dtm_1m_utm10_w_11_137.tif  dtm_1m_utm10_w_11_138.tif  dtm_1m_utm10_w_11_140.tif  dtm_1m_utm10_w_11_141.tif  dtm_1m_utm10_w_11_147.tif  dtm_1m_utm10_w_11_152.tif  dtm_1m_utm10_w_11_153.tif  dtm_1m_utm10_w_12_138.tif  dtm_1m_utm10_w_12_140.tif  dtm_1m_utm10_w_12_148.tif  dtm_1m_utm10_w_12_149.tif  dtm_1m_utm10_w_13_138.tif  dtm_1m_utm10_w_13_139.tif  dtm_1m_utm10_w_13_149.tif  dtm_1m_utm10_w_13_150.tif  dtm_1m_utm10_w_14_139.tif  dtm_1m_utm10_w_14_140.tif  dtm_1m_utm10_w_14_141.tif  dtm_1m_utm10_w_15_139.tif  dtm_1m_utm10_w_15_144.tif  dtm_1m_utm10_w_15_154.tif  dtm_1m_utm10_w_16_140.tif  dtm_1m_utm10_w_16_142.tif  dtm_1m_utm10_w_16_144.tif  dtm_1m_utm10_w_16_153.tif  dtm_1m_utm10_w_17_143.tif  dtm_1m_utm10_w_17_157.tif  dtm_1m_utm10_w_18_157.tif  dtm_1m_utm10_w_19_142.tif  dtm_1m_utm10_w_19_157.tif  dtm_1m_utm10_w_19_158.tif  dtm_1m_utm10_w_1_150.tif  dtm_1m_utm10_w_20_158.tif  dtm_1m_utm10_w_21_146.tif  dtm_1m_utm10_w_21_158.tif  dtm_1m_utm10_w_22_147.tif  dtm_1m_utm10_w_24_148.tif  dtm_1m_utm10_w_26_160.tif  dtm_1m_utm10_w_28_157.tif  dtm_1m_utm10_w_2_141.tif  dtm_1m_utm10_w_2_146.tif  dtm_1m_utm10_w_3_136.tif  dtm_1m_utm10_w_4_136.tif  dtm_1m_utm10_w_4_139.tif  dtm_1m_utm10_w_5_136.tif  dtm_1m_utm10_w_5_148.tif  dtm_1m_utm10_w_6_151.tif  dtm_1m_utm10_w_7_136.tif  dtm_1m_utm10_w_7_150.tif  dtm_1m_utm10_w_7_151.tif  dtm_1m_utm10_w_8_136.tif  dtm_1m_utm10_w_8_145.tif  dtm_1m_utm10_w_9_137.tif  dtm_1m_utm10_w_9_145.tif  dtm_1m_utm10_w_9_146.tif  dtm_1m_utm9_e_10_158.tif  dtm_1m_utm9_e_10_161.tif  dtm_1m_utm9_e_10_162.tif  dtm_1m_utm9_e_11_161.tif  dtm_1m_utm9_e_11_162.tif  dtm_1m_utm9_e_13_160.tif  dtm_1m_utm9_e_14_157.tif  dtm_1m_utm9_e_16_159.tif  dtm_1m_utm9_e_19_148.tif  dtm_1m_utm9_e_21_146.tif  dtm_1m_utm9_e_21_147.tif  dtm_1m_utm9_e_21_158.tif  dtm_1m_utm9_e_22_158.tif  dtm_1m_utm9_e_23_157.tif  dtm_1m_utm9_e_23_158.tif  dtm_1m_utm9_e_24_142.tif  dtm_1m_utm9_e_25_158.tif  dtm_1m_utm9_e_26_143.tif  dtm_1m_utm9_e_26_153.tif  dtm_1m_utm9_e_27_145.tif  dtm_1m_utm9_e_27_154.tif  dtm_1m_utm9_e_28_141.tif  dtm_1m_utm9_e_28_145.tif  dtm_1m_utm9_e_29_140.tif  dtm_1m_utm9_e_29_141.tif  dtm_1m_utm9_e_4_161.tif  dtm_1m_utm9_e_5_160.tif  dtm_1m_utm9_e_5_161.tif  dtm_1m_utm9_e_6_159.tif  dtm_1m_utm9_e_7_158.tif  dtm_1m_utm9_e_7_160.tif  dtm_1m_utm9_e_7_161.tif  dtm_1m_utm9_e_7_163.tif  dtm_1m_utm9_e_8_160.tif  dtm_1m_utm9_e_9_160.tif  dtm_1m_utm9_e_9_162.tif  dtm_1m_utm9_e_9_163.tif

Elevation API

GPXZ is an API for elevation data, including clean artefact-free lidar DEMs for much of Canada.

If you need elevation data, or help processing USGS DEMs, reach out at support@gpxz.io!