Temporal filters

[beasteers]

• adds datetime url parameter
  • exact: ?datetime=2025-01-02T00:00:00Z
  • interval: ?datetime=2025-01-02T00:00:00Z/2025-02-02T00:00:00Z
  • before: ?datetime=../2025-01-02T00:00:00Z
  • after: ?datetime=2025-01-02T00:00:00Z/..
• adds datetime/date range inputs to items.html if a date time field is available
• adds Temporal.{Instant,Start,End}Column config options to configure global column names to use for these fields
  • if both StartColumn and EndColumn are found, it will filter by time range overlap
  • otherwise it will filter if InstantColumn is contained in the range
• PR is based on Add docker-compose setup for demo/testing #188 for ease of testing (ignore changes from /demo)

Spec Used:

.15.4. Parameter datetime

Requirement 24
/req/core/fc-time-definition

A
The operation SHALL support a parameter datetime with the following characteristics (using an OpenAPI Specification 3.0 fragment):

name: datetime
in: query
required: false
schema:
type: string
style: form
explode: false
Requirement 25
/req/core/fc-time-response

A
Only features that have a temporal geometry that intersects the temporal information in the datetime parameter SHALL be part of the result set, if the parameter is provided.

B
If a feature has multiple temporal properties, it is the decision of the server whether only a single temporal property is used to determine the extent or all relevant temporal properties.

C
The datetime parameter SHALL match all features in the collection that are not associated with a temporal geometry, too.

D
Temporal geometries are either a date-time value or a time interval. The parameter value SHALL conform to the following syntax (using ABNF):

interval-closed = date-time "/" date-time
interval-open-start = [".."] "/" date-time
interval-open-end = date-time "/" [".."]
interval = interval-closed / interval-open-start / interval-open-end
datetime = date-time / interval
E
The syntax of date-time is specified by RFC 3339, 5.6.

F
Open ranges in time intervals at the start or end are supported using a double-dot (..) or an empty string for the start/end.

"Intersects" means that the time (instant or interval) specified in the parameter datetime includes a timestamp that is part of the temporal geometry of the feature (again, a time instant or interval). For time intervals this includes the start and end time.

NOTE
ISO 8601-2 distinguishes open start/end timestamps (double-dot) and unknown start/end timestamps (empty string). For queries, an unknown start/end has the same effect as an open start/end.
Example 6. A date-time
February 12, 2018, 23:20:52 UTC:

datetime=2018-02-12T23%3A20%3A52Z
For features with a temporal property that is a timestamp (like lastUpdate in the building features), a date-time value would match all features where the temporal property is identical.

For features with a temporal property that is a date or a time interval, a date-time value would match all features where the timestamp is on that day or within the time interval.

Example 7. Intervals
February 12, 2018, 00:00:00 UTC to March 18, 2018, 12:31:12 UTC:

datetime=2018-02-12T00%3A00%3A00Z%2F2018-03-18T12%3A31%3A12Z

February 12, 2018, 00:00:00 UTC or later:

datetime=2018-02-12T00%3A00%3A00Z%2F.. or datetime=2018-02-12T00%3A00%3A00Z%2F

March 18, 2018, 12:31:12 UTC or earlier:

datetime=..%2F2018-03-18T12%3A31%3A12Z or datetime=%2F2018-03-18T12%3A31%3A12Z
For features with a temporal property that is a timestamp (like lastUpdate in the building features), a time interval would match all features where the temporal property is within the interval.

For features with a temporal property that is a date or a time interval, a time interval would match all features where the values overlap.

A template for the definition of the parameter in YAML according to OpenAPI 3.0 is available at datetime.yaml.

[pramsey]

There should be some material added to the documentation to explain this new feature. Also, I could not quite see what kinds of user-facing errors are returned if the system is fed non-parseable dates, or other bad garbage parameters in the temporal columns?

[beasteers]

If there's an error parsing the parameter, it will report ErrMsgInvalidParameterValue = "Invalid value for parameter %v: %v". I added it to the filter list on API.md but haven't had a chance to dive into the Hugo docs.

But before I polish things up, I'm still trying (and failing) to get this to register as a "Time-Enabled Layer" on ArcGIS Online so it can be used with the time range slider. Do you have any idea what could be going wrong?

I was hoping it would detect time capabilities through either:

• a datetime feature parameter being present
• and/or extent.temporal in the collection metadata
• is it missing a conformance? it seems like this should be covered by ogcapi-common-1/1.0/conf/core

I'm beginning to suspect that it's just not possible with ArcGIS Online (because I am able to get it to work in QGIS). I'm hoping maybe it will work on other ArcGIS platforms (e.g. Pro) but I'll have to find someone to test it out.