The use of the time steps of the Weather API:
The time steps refer to the reference time of the Weather API. This can be called up using the ‘get_model_timesteps’ function, for example. The reference time is the same for all forecast models.
Example:
https://weather.openportguide.org/api/get_model_timesteps/gfs gives for example the following response:
The reference time (you can think about it like a "start time" of the current forecast) is is displayed as "refDate", at this example the value is "2024-05-05T00:00:00Z" which is the time in the Iso 8601 format.
The function also shows the available time steps in the ‘timesteps’ area. Here you can see that ‘timestep’ 0 corresponds to the reference time ‘refDate’. The timesteps further in the future are incremented by 1 per hour, so in our example ‘timestep’ 1 corresponds to the ISO 8601 time 2024-05-05T01:00:00Z and so on.
This is only to understand the logic behind the time steps and, in the event of an error, to be able to retrieve the available time steps in order to understand why the API may not respond as desired.
The API understands the integer value of a time step, the time in ISO 8601 format for the UTC time, as well as time UTC offsets to represent any local time zone world wide.
The API understands the integer value of a time step, the time in ISO 8601 format for the UTC time, as well as time UTC offsets to represent any local time zone world wide.
For more information about the UTC offsets for any country world wide see: https://en.wikipedia.org/wiki/List_of_UTC_offsets
Here are a few examples that are all the same for the API. In this example, we retrieve the temperature value 2 m above ground of the gfs model for the position ‘latitude’ = 54.04, ‘longitude’ = 9.075:
Here are a few examples that are all the same for the API. In this example, we retrieve the temperature value 2 m above ground of the gfs model for the position ‘latitude’ = 54.04, ‘longitude’ = 9.075:
The "refDate" at this time was 2024-05-05T00:00:00Z
| - | timestep = | 17 |
| UTC | timestep = | 2024-05-05T17:00:00Z |
| UTC | timestep = | 2024-05-05T17:00:00+00:00 |
| United States (Eastern Time Zone) | timestep = | 2024-05-05T12:00:00-05:00 |
| Japan | timestep = | 2024-05-05T02:00:00+09:00 |
The raw reply for each timestep is the same:
{"metadata":{"originatingCenter":"US National Weather Service - NCEP (WMC)","generatingProcess":"Global Forecast System Model","model":"gfs","shortName":"TMP","fullName":"Temperature","units":"°C","level":"2 m above ground","ny":721,"nx":1440,"latitudeFirstGridpoint":90.0,"latitudeLastGridpoint":-90.0,"longitudeFirstGridpoint":0.0,"longitudeLastGridpoint":359.75,"gridlengthXDirection":0.25,"gridlengthYDirection":-0.25,"refDate":"2024-05-05T00:00:00Z","forecastTime":[17,"2024-05-05T17:00:00Z"],"forcastPosition":[{"latitude":54.04},{"longtitude":9.075}]},"data":{"value":10.3}}
The same, but better to read for us humans is the presentation:
