API reference - Rasters

The GPXZ API lets you query rectangular 2D rasters directly, without iterating over a grid of individual points. Results are returned in GeoTIFF format, which is widely compatible with geospatial analysis and visualisation tools.

The /v1/elevation/raster endpoint is the place to start, just specify the desired bounds and size of your raster.

Additionally, the /v1/elevation/raw-raster endpoint gives the highest quality extracts from the GPXZ dataset with minimal interpolation and reprojection. However, the resulting rasters won't exactly match the specified bounds, and will vary in projection and resolution.

/v1/elevation/raster

Get a geotiff covering the specified area.

You must specify the extent of your raster as a bounding box.

You must also specify the size of your raster: either

• the shape in pixels with height_px and width_px,
• the resolution in metres with resolution_m, or
• the resolution in the raster projection units with resolution_x and resolution_y

If height_px and width_px are provided, the output raster will have exactly the specified bounds. If instead the resolution is provided, and the speficied bounds aren't evenly divisible by the resolution, the bounds will be buffered to ensure full coverage at the specified resolution.

Similarly, if the bounding box projection differs from the raster projection, the bounds may be buffered to ensure coverage.

The height and width of the raster must be at least 10 pixels and no larger than 2500 pixels.

HTTP request

GET https://api.gpxz.io/v1/elevation/raster?bbox_left=-122.04&bbox_right=-122.03&bbox_bottom=37.357&bbox_top=37.37&height=1000&width=1000

Here's the same request, broken up over multiple lines for readability:

GET https://api.gpxz.io/v1/elevation/raster?
            bbox_left=-122.04&
            bbox_right=-122.03&
            bbox_bottom=37.357&
            bbox_top=37.37&
            height_px=1000&
            width_px=1000

Request query parameters

Response

A geotiff.

/v1/elevation/raw-raster

Get a geotiff covering the specified area, with minimal interpolation or projection.

Compared to the main raster endpoint, this "raw" endpoint attempts to crop a slice from the GPXZ dataset with as little interpolation or reprojection as possible. The result is slightly higher quality rasters! But your pipeline needs to be able to handle rasters with a variety of resolutions and projections. Additionally, only high-resolution rasters can be obtained, no downsampled large-scale rasters.

By default the bounding box is specified in the WGS84 latitude/longitude projection, though you can specify a different projection if desired.

The output raster will at least cover the provided bounds, and will typically exceed them to avoid grid shift interpolation. If you need to specify the exact bounds of your output raster, instead use the raster endpoint.

Warping may still be done in areas where two sources meet with different resolutions/projections/grids. In this case, the lowest-resolution source will be used as the reference for warping, with ties between equal-resolution sources broken by proximity to the bounds centroid.

The width and height of the raster must be less than 5km.

HTTP request

GET https://api.gpxz.io/v1/elevation/raw-raster?bbox_left=-122.04&bbox_right=-122.03&bbox_bottom=37.357&bbox_top=37.37

Here's the same request, broken up over multiple lines for readability:

GET https://api.gpxz.io/v1/elevation/raw-raster?
        bbox_left=-122.04&
        bbox_right=-122.03&
        bbox_bottom=37.357&
        bbox_top=37.37

Request query parameters

Response

A geotiff.

/v1/elevation/supported-raster-projections

Information about the projections (coordinate reference systems) that are valid for use with the GPXZ raster endpoints.

Projections may be added to this list, but will never be removed.

Some of these projections come with either conventional or mathematical limitations on their area of use. In this case, the GPXZ will generally try to proceed regardless. As a result, the API may return a raster with bounds outside of its projection's area of use. Or, you might get an error message describing what went wrong, even if using a supported projection.

If there's a missing projection that would be useful for you, please email [email protected] and we might be able to add it.

This endpoint doesn't require authentication or count against your usage.

HTTP request

GET https://api.gpxz.io/v1/elevation/supported-raster-projections

Example response

{
  "results": [
    {
      "code": "epsg:4326", 
      "name": "WGS 84"
    }
  ], 
  "status": "OK"
}

Response

A json object listing every source.

/v1/elevation/hires-raster (Deprecated)

This endpoint has been deprecated. Please migrate to one of the other raster endpoints.

Get a geotiff covering the specified area.

If you need the elevation for a grid of points, this is the endpoint for you. Compared to splitting up your grid into points (one per pixel) and making batch point requests, this endpoint will quickly calculate all the data you need in a single request.

The rectangular area must be smaller than 10 km², and the aspect ratio less than 1:10.

For the best accuracy and fastest response, use projection=best, res_m=best, and tight_bounds=false. Other parameter combinations trigger interpolation to produce the output raster, which takes longer and reduces accuracy.

HTTP request

GET https://api.gpxz.io/v1/elevation/hires-raster?bbox_left=-122.04&bbox_right=-122.03&bbox_bottom=37.357&bbox_top=37.37&res_m=2

Here's the same request, broken up over multiple lines for readability:

GET https://api.gpxz.io/v1/elevation/hires-raster?
    bbox_left=-122.04&
    bbox_right=-122.03&
    bbox_bottom=37.357&
    bbox_top=37.37&
    res_m=2

Request query parameters

Response

A geotiff.