Time API

The Time API provides information about the available timesteps of a domain. The API offers different modes. These can be used depending on the use case.

Request

GET /v1/time/{mode}/{domain}

Parameters:

Attribute	Type	Description
mode	string	One of the following values: hourly, daily, monthly or nexthours.
domain	string	The domain the time information are required for.

Mode	Description	Default response type (see below)
hourly	Used to show non aggregated maps with an hourly or 3-hourly (depending on the domain) resolution (e.g. Temerature 3-hourly)	regular
daily	Used to show daily aggregated maps (e.g. Temperature Daily Max)	categories
monthly	Used to show monthly aggregated maps (e.g. Wind Speed Anomaly)	categories
nexthours	Used to show a aggregation over different time ranges (e.g. Accumulated Precipitation)	categories

Response

There are several types of responses. Depending on the chosen mode, the api will choose one.

All possible responses share the following attributes:

{
    "type": "...",
    "expires": "2022-02-17T16:06",
    "lastUpdate": "2022-02-17T14:41:56",
    ...
}

Attribute	Type	Description
type	string	either regular, categories or timesteps
expires	string?	optional iso8601 timestamp. At this point in time the map should be reloaded.
lastUpdate	string?	optional iso8601 timestamp of the last update. This can be used for cache invalidation.

Depending on the type there are additional attributes.

Regular

If the response type is regular the api provides the first and last timestep and an interval.

{
    ...,
    "first": "2022-02-17T00:00",
    "last": "2022-02-24T12:00",
    "interval": 10800,
    "current": "2022-02-17T18:00"
}

Attribute	Type	Description
first	string	iso8601 timestamp of the first available timestep.
last	string	iso8601 timestamp of the last available timestep.
interval	number	the interval between two timesteps in seconds.
current	string	iso8601 timestamp of the current timestep.

The Maps Plugin will generate a timeslider like this:

Categories

If the response type is categories the api provides a list of named timesteps. This is used for maps that show a daily or monthly aggregation.

{
    ...,
    "categories": [
        {
            "name": "Mon",
            "value": "2022-02-21"
        },
        {
            "name": "Tue",
            "value": "2022-02-22"
        },
        {
            "name": "Wed",
            "value": "2022-02-23"
        },
        {
            "name": "Thu",
            "value": "2022-02-24"
        },
        {
            "name": "Fri",
            "value": "2022-02-25"
        },
        {
            "name": "Sat",
            "value": "2022-02-26"
        },
        {
            "name": "Sun",
            "value": "2022-02-27"
        }
    ]
}

Attribute	Type	Description
categories	[object]	A list of available categories. Each category contains a name and a value attribute.

The Maps Plugin will generate a timeslider like this:

Timesteps

If the response type is timesteps the api provides also a list of timesteps. But in this case they are named with an iso8601 timestamp.

{
    ...,
    "format": "H:i",
    "timesteps": [
        {
            "timestep": "2022-02-21T03:00:00+00:00",
            "value": "20220221T03"
        },
        {
            "timestep": "2022-02-21T04:00:00+00:00",
            "value": "20220221T04"
        },
        {
            "timestep": "2022-02-21T05:00:00+00:00",
            "value": "20220221T05"
        },
        {
            "timestep": "2022-02-21T06:00:00+00:00",
            "value": "20220221T06"
        },
        {
            "timestep": "2022-02-21T07:00:00+00:00",
            "value": "20220221T07"
        }
    ],
    "ranges": [
        {
            "label": "3h",
            "numsteps": 3
        },
        {
            "label": "5h",
            "numsteps": 5
        }
    ]
}

Attribute	Type	Description
timesteps	[object]	A list of available timesteps. Each timestep contains a timestep that is shown in the interface and a value attribute that is used for the url.
ranges	[object]?	A optional list of ranges. Each range contains a label that is shown and a numsteps attribute that defines how many timesteps should be visible in this range. numsteps counts from bottom to top. A value of 3 will show the last three available timesteps.

The Maps Plugin will generate a timeslider like this: