New raster endpoints

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.