Capture dates

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.