Raster API improvements

The /elevation/hires-raster endpoint (for requesting a geotiff DEM by bounding box) has been upgraded:

  • There’s a new projection parameter for setting the CRS of the output raster
  • A new tight_bounds parameter has been added, for rasters that cover the bounding box without any buffer
  • The resolution parameter has a new best option
  • Improvements to error handling and performance

Existing queries will benefit from the performance improvements with unchanged response data.

But the primary benefit of these new parameters is that if you can ingest rasters of arbitrary resolution, projection, and bounds, then querying with

?projection=best&res_m=best&tight_bounds=false

will give you both the fastest possible response time as well as the most accurate results with minimal warping.

projection=best

By default, rasters are returned in UTM projection. But GPXZ sometimes stores our data in other projection systems for better accuracy: such as NZTM in New Zealand.

Using projection=best lets our API choose the output projection that minimises (or eliminates the need for) re-projecting the raster you requested, and is likely to result in the projection most suitable for analysis in your area of interest.

This does mean you need to be able to ingest rasters of arbitrary CRS. Unless you regularly update your geospatial software (e.g. PROJ, gdal, rasterio), you may want a fallback to re-requesting the raster with projection=utm in the event of a projection error when reading the output.

Also note that the projection used isn’t guaranteed to be stable across requests for the same data. In particular, new dataset releases will change the projection used to store the underlying data, and upgrades to our raster transform algorithm may change which projection is selected when the requested bounds cover multiple.

projection=latlon

Most of our customers do their analysis in UTM projection: the metre-based units are easy to work with, and it makes aligning with other UTM datasets easier.

In addition, most of GPXZ’s high resolution elevation data is stored in UTM, so returning rasters in the same projection minimises response time and avoids accuracy loss due to resampling.

But we heard from some customers that latitude-longitude projections are still being used, often for interfacing with other systems.

You can now add projection=latlon to get a raster in a epsg:4326 CRS.

res_m=best

The GPXZ dataset has coverage at different resolutions in different parts of the world.

By default, 1m resolution rasters are returned.

But for areas where our underlying data isn’t at the exact requested resolution, resampling error may be introduced. And a resolution mismatch means either rasters larger than they need to be, or a loss of horizontal precision.

Setting res_m=best lets the GPXZ API select the most appropriate resolution (typically, the minimum of all data in the requested bounding area).

Some of our data has non-integer resolutions (like Hong Kong at 0.5m, or Denmark at 1.6m).

For projections that aren’t in units of metres (i.e., a projection value of latlon or best), the resolution is approximated based on the average width and height of the bounding box: we try to make these pixels square, but can’t always. The algorithm for calculating resolution for non-metre projections may change.

tight_bounds=false

By default, the returned raster is guaranteed to at least cover the requested bounds, and may extend beyond them.

As well as ensuring bounds coverage, this improves the accuracy of any interpolation you do near the edges of the raster.

Further, in most cases, buffering bounds lets GPXZ align your output raster with the grid of the underlying data, reducing the need for accuracy-reducing re-projection.

But if you would like to reduce this buffer as much as possible, you can set tight_bounds=true.

For projection=latlon projected rasters, tight_bounds=false guarantees the output raster will exactly match the bounding box.

For rasters in other projections, the buffer is reduced as small as possible. But it is often not geometrically possible to completely remove the buffer while still ensuring coverage of the bounding box.

Coverage of the bounding box is guaranteed (within ε² for tight_bounds=false).

If res_m is specified to a value that doesn’t evenly divide the bounding box, the bounds will be buffered rather than the resolution altered.

Improved validation

A bug has been fixed that could result in valid but incomplete rasters being returned.

All successful requests are guaranteed to be valid geotiff files, and have no NODATA regions.

Improved performance

Responses are much faster now.