Date/Time Description

Dates and times are specified according to the ISO-86011 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 20th of January 2015, 18:45 UTC You can specify the time zone by adding the deviation from UTC: 2015-01-20T18:45+01:00 20th of January 2015, 19:45 CET

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: 2022-11-25T13:00:00ZP5D:PT12H https://api.meteomatics.com/2022-11-25T13:00:00ZP5D:PT12H/t_2m:C/47.4245,9.3767/csv?model=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 28th of May 2017 at 13 UTC and lasts 5 days until the 2nd 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: 2022-11-25T13:00:00Z--2022-11-28T13:00:00Z:P1D https://api.meteomatics.com/2022-11-25T13:00:00Z--2022-11-28T13:00:00Z:P1D/t_2m:C/47.4245,9.3767/csv?model=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 28th of May 2017 at 13 UTC until the 30th 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: 2022-11-24T18Z,2022-11-25T18Z,2022-11-28T18Z https://api.meteomatics.com/2022-11-24T18Z,2022-11-25T18Z,2022-11-28T18Z/relative_humidity_2m:p/47.4245,9.3767/csv?model=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 20th, the 21st and the 22nd 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: 2022-11-24T18Z,2022-11-25T18ZPT2H:PT20M https://api.meteomatics.com/2022-11-24T18Z,2022-11-25T18ZPT2H:PT20M/relative_humidity_2m:p/47.4245,9.3767/csv?model=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?model=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?model=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:

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

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