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 notationExample for single point in time:
2015-01-20T18:45Z20th of January 2015, 18:45 UTC You can specify the time zone by adding the deviation from UTC:
2015-01-20T18:45+01:0020th 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
PT within the command.
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.2The definition of the period starts with
Pand 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
PTfollows 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
validdate;t_2m:C 2017-05-28T13:00:00Z;26.7 2017-05-29T13:00:00Z;26.5 2017-05-30T13:00:00Z;26.1This 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 pointsYou 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:
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.1This 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:
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
ShortcutsThere 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
nowcan be shifted by hours (H), minutes (M) and seconds (S). For example,
now--now+5H:PT1Hhttps://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
tomorrowwill expand to
YYYY-MM-DD. These shortcuts can be shifted by years (Y), months (M) and days (D). For example,
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:
yesterdayT00:00Z--todayT12:00Z:PT3Hhttps://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 parametersIf 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:mmyields 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:
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
3His chosen, according to the interval parameter
- https://api.meteomatics.com/2023-03-20T12ZP1D:PT1H/wind_speed_mean_10m_1h:ms/47.4245,9.3767/html?model=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/2023-03-20T12ZP1D:PT1H/wind_gusts_10m_1h:ms/47.4245,9.3767/html?model=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.
SummaryThe following table shows a summary of all described possibilities:
|Single point UTC||
|Single point local time||
|Time Period (fixed length)||
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)||
|Comma-separated list of sorted time points and/or periods||
no additional time specification required
time needs to be specified additionally
- ISO-8601 date format: https://www.iso.org/standard/40874.html, http://en.wikipedia.org/wiki/ISO_8601