How to support time in this API?

[joanma747]

Linked to https://github.com/opengeospatial/ogcapi-maps/issues/16

In principle the essential building block also for not OGC "people": .../{tilemetrix}/{tilerow}/{tilecol} defined in OGC API tiles; tileset conformace class (a.k.a. core)

can be applied to any path. so, in principle we can imagine that a part from our common path {datasetAPI}/collections/{collectionId}/tiles defined in OGC API tiles; collection {datasetAPI}/collections/{collectionId}/styles/{styleId}/map/tiles defined in the OGC API maps; tiles with styles conformace class

We could have other paths. Example {datasetAPI}/collections/{collectionId}/{elevation}/{time}/tiles The OpenAPI document for the service should specify this paths parametres and everybody should be happy.

or we might need a "word" in between to help the parser to know we are doing {datasetAPI}/collections/{collectionId}/dimension/{elevation}/dimension/{time}/tiles

Actually I realized that we defined an implicit rule for OGC API's. To use the tiles building block you should precede it by the word "tiles/". We should clarify this. It should be a recommendation in the core building block

[ghobona]

@robinhoutmeyers demonstrated OGC API - Tiles support of Time during the Code Sprint in April last year.

See the section titled “Time and Altitude Dimensions” at https://github.com/opengeospatial/OGC-OS-Sprint-04-2020/tree/master/Screenshots

[chris-little]

@joanma747 I think {datasetAPI}/collections/{collectionId}/{elevation}/{time}/tiles is making it too complicated. You wouldn't have {datasetAPI}/collections/{collectionId}/{location]/tiles would you?

I think you should make time and elevation first class citizens of the CRS space. They should go after the "?"

Two cases to consider: a 3/4D bounding box where time is a proper CRS dimension, such as Unix seconds (as in WKT), or a 2/3D bounding box with a time instant or interval specified in a calendar, such as IETF RFC 3339 profile of ISO8601.

[joanma747]

• NetCDF tiles will have all times and dimensions there.
• We could have query parameters for the extra dimensions (like in WMS)
• We could have path parameters (like in WMTS)

So far opinions seem to converge on using a query parameters.

In the past there was an argument to have path parameter: it was better cached. The query parameters can help e.g. subsetting (?subset=time("2020-01-01":"2020-01-20"))

Another argument for having query parameters is extensibility of many "unforeseen" dimension names.

It seems that the two options are needed. So the "dimensions" extension document will need to discuss both approaches.

[mcechini]

Perhaps then we're talking about two activities:

1. How to define custom dimensions... which per our discussion today we began to discuss that both query parameter and path-based approaches are needed for various reasons. This could apply to time, but also elevation, etc...
2. How to define time ... which I think is a separate (and historically very complicated) topic. As a potential implementer of an OGCAPI-tiles API, I do not want to have to struggle to defend the definition of "time" with clients (as we currently do in WMTS).

Neither of these seem very specific to Tiles (or Maps).

[bradh]

Perhaps it would help to explicitly identity why you want time (or elevation, or other custom dimensions). I'm completely in agreement that it might be useful for something, and there is likely other discussion and analysis that supports that.

However the discussion here is a long way to "what should the format look like" without an example use case as to what we're trying achieve. For example, a discussion of weather forecasts might identify that there are (at least) two kinds of time in use - the time the forecast is released/calculated, and when I'm looking to (e.g. the forecast for next Monday might be different between this morning's estimate and this afternoon's estimate). Note: I'm not interested in encoding T / tau at this stage, just trying to get the needs made explicit.

[mcechini]

Going back a number of years, there was a very thorough approach laid out in Testbed 12 for time in WMTS (i.e. OGCAPI-Tiles).

For our NASA visualizations, the primary use case is that we have visualization layers that vary over hourly/daily/weekly/monthly/yearly temporal intervals... and we need a way to:

1. Provide a list of available time(s) to a client
2. Support requests for those time(s)

[chris-little]

The approach of limiting precision (not accuracy) to nanoseconds is commendable, but the Engineering Report is focussed on ISO8601, which is a calendar notation, and therefore prone to errors of seconds if leap-seconds not accounted for, or much worse (for example, Apple forgot a leap day not long ago). IETF RFC 3339 is a restrictive profile of ISO8601 and better to reference. However it very very carefully makes no statement about arithmetic, only that timestamps can be correctly ordered. i.e. before/during/after operations are valid, but not subtracting times to get a duration. WKT is well accepted and uses Unix seconds as a coordinate, and does not have the calendrical problems. See some good examples in Annex D of the Abstract Topic. There is also a Best Practice for the handling of Time and Elevation for WMS1.3 at OGC12-111r1 HTH.

[bradh]

For some purposes, you don't want leap seconds. For other purposes you do. If the user thinks we're in UTC and we don't deal with leap seconds, eventually it'll turn out surprising. Some people record in UT1, others in TAI.

Hence my concern about identifying the problem we want to solve, and only adding enough functionality / complexity to deal with that.

If this gets too hard, maybe its not a single profile. Maybe we have "simple time" and "UT1 time" and "TAI time" profiles (or whatever it gets called).

[joanma747]

I believe the new Annex K in the 2DTMS standard includes part of the solution. https://github.com/opengeospatial/2D-Tile-Matrix-Set/blob/master/standard/annex_k.adoc

[chris-little]

@joanma747 I agree that the Annex K apaporach is the most appropriate approach for sub-dividing n-D spaces. Mathematically, 2, 3 and 4D are rather special in having regular Polygons/Polyhedra/4-Polytopes. For 5 or more dimensions, there are only 2 fundamental geometrical objects/patterns - simplexes (nD triangles/tetrahedra) and orthoplexes (nD square/cubes, so the Annex K approach will work for any number of dimensions, and of course corresponds to orthogonal coordinate dimensions and also W3C Data Cube Vocabulary.

[jerstlouis]

SWG 2021-07-01: Annex K allows to describe additional dimensions. With approaches 2 & 3, it would also allow to index different "time tiles". However, with approach 1, a datetime or subset parameter would still be useful to slice or trim the temporal dimension.

Should datetime and subset be included as query parameters / conformance classes for OGC API - Tiles: Part 1? At the moment they are not included.

Feedback from the meeting today is yes we should add these as conformance classes. subset is also already proposed as a Common building block.

[jeffharrison]

I would say Yes...

[mcechini]

I like that there is discussion here. I am concerned that the approach being proposed for time is addressing too many options and will be difficult to ensure consistency across implementations. While the specification should support the large variety of temporal implementations, I don't want to end up back where we have been for the last decade with client (i.e. Esri and QGIS) adoption of time in WM[T]S services. WMTS essentially has no formal time definition and WMS is a bit wishy-washy. We just now are making tangible progress with Esri on ArcGIS Pro and Online supporting time time-enabled WMS. WMTS is a lost cause.

So... please let's make sure we have a simple solution that addresses a majority large variety of use cases to which servers and clients could build to.

[jeffharrison]

Yes, agreed...

"So... please let's make sure we have a simple solution that addresses a large variety of use cases to which servers and clients could build to."

[jerstlouis]

@mcechini There are two different fundamental use cases which I think are equally important:

a) The client specifying a custom time range, whether a single datetime (slice) or trim (lower & upper bound) b) The data being readily available in an extended TileMatrixSet with a temporal dimension also organized as temporal tiles

The simplest approach is a), but in terms of caching and performance for a large number of clients b) is superior as requests are more likely to be repeated and cached.

To address a), there are two equvalent options based on on building blocks proposed for OGC API - Common which different people will find one or the other more familiar:

1) datetime: datetime=2018-02-12T00:00:00Z/2018-03-18T12:31:12Z as used in Features 2) subset: subset=datetime("2018-02-12T00:00:00Z":"2018-03-18T12:31:12Z") as used in Coverages, using the same parameter to subset any number of dimensions, including time

Rather than picking one, I would prefer to make them separate conformance classes (in Part 1: Core) and recommend that servers with temporal support implement both to maximize interoperability and the convenience for users of the API.

Approach b) would be covered in an extension, based on Annex K.

I believe this would strike the right balance of simplicity while addressing the majority of use cases, and ensuring interoperability.

[chris-little]

@jerstlouis @mcechini @jeffharrison I like the two simple proposals. But to inform my agnosticism and decision making:

(1) has the advantage of being pure ISO8601 notation, and it could be extended to cover more complex patterns than just an instant or temporal interval, such as repeating patterns, as defined consistently in ISO8601. And (1) is used in a published API-Features.

I am not sure whether the separator slash (/) is a weakness, causing confusion when parsing URIs.

(2) has the datetimes as literals, and overloads the colon (:). I have no idea whether these are weaknesses or sources of potential parsing confusion. Why not use slash (/) for consistency with (1)?

I think consistency across the OGC APIs is essential, and further consistency with previous standards such as WMS is desirable.'

The existing syntaxes that could be used as models include: regular expressions, URNs, URLs, ISO8601, WKT, WMS.

[jerstlouis]

@chris-little To clarify, 2) is what is currently specified in OGC API - Coverages, and proposed as a general common building block for subsetting on any dimension.

The subset parameter originated In WCS, where a comma (,) was used rather than a colon (:), and separate subset were required for each dimension. In OGC API - Coverages, we decided to allow combining (explode parameters = false), and replaced the comma by a colon to identify an interval (trim). That actually makes it easier to parse as it distinguishes from the comma used to separate multiple dimensions being subset on.

[mcechini]

I suppose then that we are most interested in the Annex K / Temporal dimension implementation as that is fundamentally how we approach time within our services. Time is a fixed dimension to our TileMatrixSet. The implementation of those extraDimension elements is a little fuzzy to me (i.e. division and resolution. But perhaps that is just a separate conversation to be had.

If the proposed datetime and/or subset approaches are used to allow clients to specify a date/time range, it's not clear how that correlates to a server indicate only supporting fixed ranges (e.g. in alignment with a "daily" temporal dimension). Perhaps the the Tiles API would use the N-Dimension time and MAPS API the datetime/subset parameters.

I see the conformance class for specifying datetime as a supported query parameter, but not information on how a server would indicate to a client what the valid values are (e.g. the Layer/Dimension/Value[] we have in WM[T]S Capabilities documents) Is that defined somewhere?

[jerstlouis]

@mcechini

not information on how a server would indicate to a client what the valid values are

The /collections/{collectionId} resource provides temporal information as part of the extent, including an overall interval, as well as optionally more specific intervals within that if the data is sparse.

An extension based on Annex K could provide further information as part of the tileset metadata, such as the temporal resolution (e.g. daily), even for this first approach (no explicit tiling of extra dimensions).

Another mechanism for providing the extra information would be offering the domainset from Coverages in the same API, e.g.: https://maps.ecere.com/ogcapi/collections/blueMarble/coverage/domainset?f=json https://maps.ecere.com/ogcapi/collections/blueMarble/tiles/GNOSISGlobalGrid/0/0/0?datetime=2004-07

The implementation of those extraDimension elements is a little fuzzy to me (i.e. division and resolution. But perhaps that is just a separate conversation to be had.

• resolution would be the resolution of the data, regardless of how or whether it is tiled temporally or not. e.g. if using daily temporal resolution, for a netCDF file at .../{tileMatrix}/{tileRow}/{tileCol} (only geographic tiling) or at .../{tileMatrix}/{tileRow}/{tileCol}/{tileTime} (using temporal tiling), each tile will contain one set of values for the geographic extent of the tile for each day contained within the tile. temporalResolution is to express temporal units in more familiar terms while properly handling the varying nature of those units, like leap seconds and unequal days/months/years.
• divisions would be in how many tiles the full temporal interval has been divided (analogous to tileRows with e.g. latitude, and tileCols with e.g. longitude). temporalDivision is to express temporal units in more familiar terms while properly handling the varying nature of those units, like leap seconds and unequal days/months/years. Although divisions should still be included as a readily available number where {tileTime} will range from 0..(divisions-1).

e.g. if temporalDivision is month and temporalResolution is day, then each tile at .../{tileMatrix}/{tileRow}/{tileCol}/{tileTime} will contain one set of values for the geographic extent of the tile for each day of one month.

If your service just has a single value for each day, and you don't necessarily regroup days in months or otherwise and don't have temporal overviews, then I think the Annex K extension in terms of approaches 2 & 3 where an additional tile path element is introduced (.../{tileTime}) is not necessarily needed. However the description aspect might come in handy, as currently the collection extent does not include resolution information (as discussed above).

With approaches 2 & 3 however, tiles could contain more detailed resolutions for deeper tile matrices, while offering a "temporal overview" (lower temporal resolution) at lower tile matrices.

[joanma747]

This is linked to a discussion on EDR: https://github.com/opengeospatial/ogcapi-environmental-data-retrieval/issues/332

---

For the datetime parameter

Advanced Option not include in part 1. We will create a new conformance class extra dimensions

It will include this requirements module: https://github.com/opengeospatial/ogcapi-common/blob/master/api_modules/datetime/requirements_module_datetime.adoc

datetime= with syntax specified here: https://github.com/opengeospatial/ogcapi-common/blob/master/api_modules/datetime/requirements/REQ_rc-datetime-definition.adoc

/collections/{collectionId}/elevation/{elevation}/{TileMatrixSetId}/{TileMatrix}/{TileRow}/{TileCol}

Option A: DEcided to be implemented in the standard as a single conformance class

We will create a new conformance class for time only

It will include this requirements module: https://github.com/opengeospatial/ogcapi-common/blob/master/api_modules/datetime/requirements_module_datetime.adoc

datetime= with syntax specified here: https://github.com/opengeospatial/ogcapi-common/blob/master/api_modules/datetime/requirements/REQ_rc-datetime-definition.adoc

Servers will also support:

https://github.com/opengeospatial/ogcapi-common/tree/master/api_modules/subset where axisname SHALL be "datetime" to subset the time dimension

If neither "datetime" nor "subset=datetime(...)" are specified by the client, the server SHALL return a tile with what is considered the most up to date existing data.

Other extensions could add the support to other extra dimensions for tiles.

Permission: The closest or last previous time for which a tile is available for a certain tile column and row may be returned. An Earth Observation use case for this permission is to allow retrieving a tile of the last available imagery on or before the requested datetime, taking into account that a certain geographic area may only be observed at an interval of "every few days".

Header in the response could return a time interval of the returned data (STA phenomenon-time?)

---

For the metadata describing that correct values for times we will relay on other standards like the OGCAPI Common or 2DTMS. No action required in Tiles part 1.

we will adopt the collection extent that allow for a temporal interval and will have a temporal resolution (see https://github.com/opengeospatial/ogcapi-coverages/issues/63) and eventually could have a list of instantaneous times. This solves only the "collections" tiles but not the "dataset" "tiles". Do we need to add something at the TileSetMetadata level?. This will require a "2DTMS v2.1 - time". In OGC API Tiles we can "assume" that this will happen in the future.

[joanma747]

All suggested changes applied in our regular telco