Timestamps

The HTTP API uses RFC3339 timestamps both in different JSON objects and in query parameters. Most programming languages have built-in support or a library available for both formatting and parsing a RFC3339 timestamp.

The HTTP API currently normalizes timestamps to UTC in its output.

Example RFC3339 timestamps

1985-04-12T23:20:50.52Z
1990-12-31T15:59:60-08:00
2023-10-01T04:19:03.636Z

JSON

In JSON objects the timestamps is represented by a string with the formatted RFC3339 timestamp.

Query support - single

Exact date

Exact dates are supported both in RFC3339 format and in a more lenient format which takes the date in ISO8601 format with optional hours and minutes.

Examples of lenient format:

• 2023-11-01 - will be treated as 00:00 UTC on the given date
• 2023-11-01 10:00 - will be treated as 10:00 UTC on the given date

Use in a query criteria:

{
  "type": "propertyHere",
  "criteria": "2023-11-01 10:00"
}

Query support - ranges

When timestamps are used in queries they can be queried exactly or as a range.

Exact dates and relative dates can be combined into a range using a JSON object with from and to properties. One of the properties need to be specified, but if the other is skipped it is treated as an open range.

Open range which matches all up to (and including) November 1st 2023:

{
  "type": "propertyHere",
  "criteria": {
    "to": "2023-11-01"
  }
}

Open range which matches all from (and including) October 1st 2023 and forward:

{
  "type": "propertyHere",
  "criteria": {
    "from": "2023-10-01"
  }
}

Open range which matches all between (and including) October 1st 2023 and November 1st 2023:

{
  "type": "propertyHere",
  "criteria": {
    "from": "2023-10-01",
    "to": "2023-11-01"
  }
}