Date/Time Description

Dates and times are specified according to the ISO-8601¹ format (YYYY-MM-DDThh:mm:ssZ). All times are in UTC. Note that the part containing time specifications (Thh:mm:ss) is optional.

General notation

Example for single point in time: 2015-01-20T18:45Z stands for 20^th of January 2015, 18:45 UTC. You can specify the time zone by adding the deviation from UTC: 2015-01-20T18:45+01:00 stands for 20^th of January 2015, 18:45 CET, or equivalently 20^th of January 2015, 17:45 UTC.

Specification of time periods

a) Start point + duration You need to define the beginning and the duration of the desired period. A period of date elements always starts with the duration designator P and is followed by the desired period (years (Y), months (M) and days (D)). For periods of time elements the time designator T follows (hours (H), minutes (M) and seconds (S)). The result is a list of ascending time steps beginning with the defined starting point and ending with the last time step of the defined period. Additionally, you have to specify the spacing of the time period - depending on your needs you may want hourly time steps or just daily steps? The spacing is also denoted with P or PT within the command. Example: 2024-12-19T13:00:00ZP5D:PT12H https://api.meteomatics.com/2024-12-19T13:00:00ZP5D:PT12H/t_2m:C/47.4245,9.3767/csv?source=mix

validdate;t_2m:C
2017-05-28T13:00:00Z;26.7
2017-05-29T01:00:00Z;20.9
2017-05-29T13:00:00Z;26.5
2017-05-30T01:00:00Z;18.8
2017-05-30T13:00:00Z;26.1
2017-05-31T01:00:00Z;17.1
2017-05-31T13:00:00Z;22.9
2017-06-01T01:00:00Z;16.4
2017-06-01T13:00:00Z;20.1
2017-06-02T01:00:00Z;16.0
2017-06-02T13:00:00Z;23.2

The definition of the period starts with P and means that the time period starts on the 28^th of May 2017 at 13 UTC and lasts 5 days until the 2^nd of June 2017 at 13 UTC. After PT follows the spacing of the time period. In this case the time period is divided into steps of 12 hours. The example link fetches temperature data for a given location for the specified time steps.

b) Start point + end point Alternatively, you can specify the start point and the end point and define the desired spacing. Note that the two dates are separated by --. Example: 2024-12-19T13:00:00Z--2024-12-22T13:00:00Z:P1D https://api.meteomatics.com/2024-12-19T13:00:00Z--2024-12-22T13:00:00Z:P1D/t_2m:C/47.4245,9.3767/csv?source=mix

validdate;t_2m:C
2017-05-28T13:00:00Z;26.7
2017-05-29T13:00:00Z;26.5
2017-05-30T13:00:00Z;26.1

This command represents the time period from the 28^th of May 2017 at 13 UTC until the 30^th of May 2017 at 13 UTC with an interval length of 1 day. Again, the example link fetches temperature data.

List of time points

You can also enter a list of dates and times. The time points have to be comma separated and sorted from the earliest to the latest. Example: 2024-12-18T18Z,2024-12-19T18Z,2024-12-22T18Z https://api.meteomatics.com/2024-12-18T18Z,2024-12-19T18Z,2024-12-22T18Z/relative_humidity_2m:p/47.4245,9.3767/csv?source=mix

validdate;relative_humidity_2m:p
2018-10-20T18:00:00Z;76.7
2018-10-21T18:00:00Z;71.9
2018-10-22T18:00:00Z;70.1

This series of time points would fetch data (relative humidity in this example) for the 20^th, the 21^st and the 22^nd of October 2018 at 18 UTC. Time periods and time points can be mixed, as long as the resulting list of time points is in ascending order. Example: 2024-12-18T18Z,2024-12-19T18ZPT2H:PT20M https://api.meteomatics.com/2024-12-18T18Z,2024-12-19T18ZPT2H:PT20M/relative_humidity_2m:p/47.4245,9.3767/csv?source=mix

validdate;relative_humidity_2m:p
2018-10-20T18:00:00Z;76.7
2018-10-21T18:00:00Z;71.9
2018-10-21T18:20:00Z;78.9
2018-10-21T18:40:00Z;80.4
2018-10-21T19:00:00Z;82.9
2018-10-21T19:20:00Z;82.0
2018-10-21T19:40:00Z;83.7
2018-10-21T20:00:00Z;85.6

Shortcuts

There are several shortcuts available for easier access to recent data. If you use such a shortcut in a command it will expand to full date/time notation. There are two kinds of shortcuts: a) Shortcuts including date and time In order to represent the current date and time you can use now. This command will expand to YYYY-MM-DDThh:mm:ssZ. The shortcut now can be shifted by hours (H), minutes (M) and seconds (S). For example, now+2H, now+30M and now+60S. Example: now--now+5H:PT1H https://api.meteomatics.com/now--now+5H:PT1H/precip_3h:mm/47.4245,9.3767/html?source=mix This example fetches precipitation data for the current time until 5 hours ahead with a step size of one hour. b) Shortcuts including date only: additional specification of time required The shortcuts yesterday, today, tomorrow will expand to YYYY-MM-DD. These shortcuts can be shifted by years (Y), months (M) and days (D). For example, yesterday-1Y, today-3M. tomorrow+2D. Note that you have to add a time specification to these shortcuts. The shortcuts can also be used in a list of time points: yesterdayT18Z,todayT18Z,tomorrowT18Z. Example: yesterdayT00:00Z--todayT12:00Z:PT3H https://api.meteomatics.com/yesterdayT00:00Z--todayT12:00Z:PT3H/relative_humidity_2m:p/47.4245,9.3767/html?source=mix This example fetches relative humidity data from yesterday with a step size of 3 hours.

Interval parameters

If you query parameters, which are averaged or accumulated over a certain time interval, you have to note that all time intervals are right-bounded. This means that a parameter like precip_3h:mm yields the accumulated precipitation sum over the previous 3 hours. So, the value at 18 UTC represents the precipitation sum from 15 UTC until 18 UTC. Examples:

https://api.meteomatics.com/2024-12-19T12ZP1D:PT3H/precip_3h:m/47.4245,9.3767/html?source=mix A useful specification of the time interval for the query is the length of the interval of the averaged/accumulated parameter. In this example a time interval of 3H is chosen, according to the interval parameter precip_3h:mm
https://api.meteomatics.com/2024-12-19T12ZP1D:PT1H/wind_speed_mean_10m_1h:ms/47.4245,9.3767/html?source=mix This example queries the mean wind speed within an hour. A value of 4.2 m s^-1 at 3 UTC means that the mean wind speed between 2 UTC an 3 UTC was 4.2 m s^-1.
https://api.meteomatics.com/2024-12-19T12ZP1D:PT1H/wind_gusts_10m_1h:ms/47.4245,9.3767/html?source=mix This example queries the wind gusts over an hour. For example, a value of 9.8 m s^-1 at 15 UTC means that the maximum wind gust between 14 UTC an 15 UTC was 9.8 m s^-1.

Summary

The following table shows a summary of all described possibilities:

Time	Description	Example
Single point UTC	`<isodate>`	`2015-01-20T18Z` - 20th January 2015, 18:00 UTC
Single point local time	`<isodate>`	`2015-01-20T14:35+01:00` - 20th January 2015, 14:35, time zone UTC+01:00
Time Period (fixed length)	`<isodate>P<duration>:P<step>`	`2017-05-28T13:00:00ZP10D:PT1H` (a period of 10 days with a step size of 1 hour) Options for duration and step: 1D: 1 day 1W: 1 week 1M: 1 month 1Y: 1 year T1H: 1 hour T1M: 1 minute T1S: 1 second and combinations of the previous, e.g. 1DT1H
Time Period (fixed end)	`<isodate>--<isodate>:P<step>`	`2017-05-28T13:00:00Z--2017-05-30T13:00:00Z:P1D` (a period between two dates with step size of 1 day
Comma-separated list of sorted time points and/or periods	`<isodate or period>,<isodate or period>,...,<isodate or period>`	`2018-10-20T18Z,2018-10-21T18Z,2018-10-22T18Z`, `2018-10-20T18Z,2018-10-21T18ZPT2H:PT20M`, `2018-10-20T18ZPT2H:PT20M,2018-10-21T18ZPT2H:PT20M`
Shortcut `now`	`<shortcut>[<shift>]` no additional time specification required	`now`, `now+1H`, `now-30M`
Shortcuts `today`, `yesterday`, `tomorrow`	`<shortcut>[<shift>]` time needs to be specified additionally	`todayT01:30:00Z`, `today+1DT20:45:00Z`, `yesterday-2DT10:00:00Z`, `yesterdayT00:00:00Z--tomorrow+1DT12:00:00Z:PT1H` (a period from yesterday at noon (UTC) to the day after tomorrow at noon (UTC) with 1-hour step)

Footnotes

ISO-8601 date format: https://www.iso.org/standard/40874.html, http://en.wikipedia.org/wiki/ISO_8601