Tidetech WMTS Capabilities Document Time Dimension

 

Most Web Map capabilities documents list each timestamp available for each layer. This is fine for services that provide a relatively small number of timestamps. The addition of hindcast to our Web Map datasets, providing from 12 months up-to 5 years of historical tiles, means that our capabilities documents can contain anywhere up-to 15,000 timestamps for each layer, resulting in a file that is slow to produce, transfer and parse.

 

In order to avoid this problem, the Tidetech WMTS has adopted the convention used by NASA in their Global Imagery Browse Services (GIBS), and other organisations, which allows them to serve historical imagery over any temporal range.

 

Rather than listing each timestamp, this convention describes the minimum timestamp, maximum timestamp, and the duration of the timestep.

 

Here is an example of a time dimension from the old capabilities document:

<Dimension>

<ows:Identifier>Time</ows:Identifier>
<ows:UOM>ISO8601</ows:UOM>
<ows:Title>Time</ows:Title>
<Default>2019-09-04T00:00:00Z</Default>
<Value>2019-09-04T00:00:00Z</Value>
<Value>2019-09-04T03:00:00Z</Value>
<Value>2019-09-04T06:00:00Z</Value>
<Value>2019-09-04T09:00:00Z</Value>

... (omitted for brevity)

<Value>2019-09-13T21:00:00Z</Value>

</Dimension>


Under the new format the same information is described by the following:

<Dimension>

<ows:Identifier>Time</ows:Identifier>
<ows:UOM>ISO8601</ows:UOM>
<ows:Title>Time</ows:Title>
<Default>2019-09-04T00:00:00Z</Default>
<Value>2019-09-04T00:00:00Z/2019-09-13T21:00:00Z/PT10800S</Value>

</Dimension>


As you can see, the Value tag now contains three values separated by "/" - the start_timestamp, end_timestamp, and timestep_duration. The duration is specified as an ISO8601 duration, see https://en.wikipedia.org/wiki/ISO_8601#Durations. For more information on GIBS see https://developer.earthdata.nasa.gov/gibs/gibs-api-for-developers#GIBSAPIforDevelopers-TimeDimension.


To generate all available timestamps, start at the start_timestamp, and add the timestep_duration repeatedly until you reach the end_timestamp.

 

Some basic pseudo code that would achieve this would be:

timesteps = []
current_timestep = start_timestep
while (current_timestep <= end_timestep) {
timesteps.push(current_timestep)
current_timestep = current_timestep + timestep_duration
}


There are libraries designed to handle these formats, such as these for JavaScript: https://www.npmjs.com/package/iso8601-duration orhttps://www.npmjs.com/package/moment with https://www.npmjs.com/package/moment-duration-format, or for Python: https://pypi.python.org/pypi/isodate