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:
Available variables (weather data)
gfs-model
Timesteps
- Days 1-3: hourly (Timesteps 0, 1, 2, ..., 70, 71, 72)
- Days 4-10: 3-hourly (Timesteps 75, 78, 81, ..., 234, 237, 249
Variablen
| name | long name | level | description | |
| 1. | PRMSL | Pressure Reduced to MSL [Pa] | mean sea level | Air pressure, calulated to the medium sea level ("normal air pressure") |
| 2. | VIS | Visibility [m] | surface | Visibility is the measure of the distance at which an object or light can be clearly discerned. It depends on the transparency of the surrounding air and as such, it is unchanging no matter the ambient light level or time of day. |
| 3. | UGRD | U-Component of Wind [m/s] | 10 m above ground | Wind component to the north (negative values mean to the south) 10 m above ground |
| 4. | VGRD | V-Component of Wind [m/s] | 10 m above ground | Wind component to the east (negative values mean to the west) 10 m above ground |
| 5. | GUST | Wind Speed (Gust) [m/s] | 10 m above ground | max. gust speed 10 m above ground |
| 6. | TMP | Temperature [C] | 2 m above ground | Air temperature 2 m above ground |
| 7. | RH | Relative Humidity [%] | 2 m above ground | Relative Humidity 2 m above ground |
| 8. | TCDC | Total Cloud Cover [%] | entire atmosphere | Cloud cover, regardless of the height of the atmosphere |
| 9. | HINDEX | Haines Index [Numeric] | surface |
This is a fire weather index based on the stability and moisture content of the lower atmosphere and measures the potential for existing fires to develop into large fires (although it is not a predictor of fire outbreaks). Haines Index values of 4 (low), Haines Index values of 5 (moderate), and Haines Index values of 6 (high). The overall Haines Index ranges from 2 to 6, with 6 representing the highest potential for large fires. The Haines Index is calculated by taking the sum of the atmospheric stability index (term A) and the lower atmospheric dryness index (term B). The stability index is determined from measurements of the temperature difference between two atmospheric levels and the dryness index from measurements of the dew point depression. |
| 10. | TSOIL | Soil Temperature [C] |
0-0.1 m below ground |
Ground temperature |
| 11. | SOILW | Volumetric Soil Moisture Content [%] | 0-0.1 m below ground 0.1-0.4 m below ground 0.4-1 m below ground 1-2 m below ground |
Moisture content of the soil |
| 12. | SNOD | Snow Depth [m] | surface | Snow depth |
| 13. | ICETK | Ice Thickness [m] | surface | Ice thickness |
| 14. | DPT | Dew Point Temperature [C] | 2 m above ground | Dew point temperature The dew point, also known as the dew point temperature, is the temperature at which the moisture contained in a volume of air condenses and precipitates on solid surfaces as a film of water (dew) when the volume of air cools down at constant pressure. |
| 15. | APTMP | Apparent Temperature [C] | 2 m above ground | Apparent temperature |
| 16. | ICEG | Ice Growth Rate [mm/h] | 10 m above mean sea level | Growth speed for ice on surfaces, important for ships, as they capsize if their superstructures are too heavy due to ice. |
| 17. | PRATE | Precipitation Rate [mm/h] | surface | Amount of precipitation |
| 18. | CSNOW | Categorical Snow [1 = true] | surface | Type of precipitation: 1 = snow |
| 19. | CICEP | Categorical Ice Pellets [1 = true] | surface | Type of precipitation: 1 = Sleet |
| 20. | CFRZR | Categorical Freezing Rain [1 = true] | surface | Type of precipitation: 1 = freezing rain |
| 21. | CRAIN | Categorical Rain [1 = true] | surface | Type of precipitation: 1 = rain |
| 22. | VEG | Vegetation [%] | surface | Coverage of the earth's surface with vegetation (e.g. jungle: 100%, desert: 0%) |
| 23. | SOTYP | Soil Type [-] | surface | |
| 24. | SUNSD | Sunshine Duration [h] | surface | Sunshine duration |
| 25. | CAPE | Convective Available Potential Energy [J/kg] | surface |
In meteorology, convective available potential energy (commonly abbreviated as CAPE),[1] is the integrated amount of work that the upward (positive) buoyancy force would perform on a given mass of air (called an air parcel) if it rose vertically through the entire atmosphere. Positive CAPE will cause the air parcel to rise, while negative CAPE will cause the air parcel to sink. Nonzero CAPE is an indicator of atmospheric instability in any given atmospheric sounding, a necessary condition for the development of cumulus and cumulonimbus clouds with attendant severe weather hazards. For details see: https://en.wikipedia.org/wiki/Convective_available_potential_energy |
| 26. | LCDC | Low Cloud Cover [%] | low cloud layer | Cloud cover up to an altitude of approx. 7000 feet (2134 m) |
| 27. | MCDC | Medium Cloud Cover [%] | middle cloud layer | Cloud cover from approx. 7000 feet (2134 m) up to 15000 feet (4572 m) |
| 28. | HCDC | High Cloud Cover [%] | high cloud layer | Cloud cover above 15000 feet (4572m) |
| 29. | DSWRF | downward short-wave radiation flux [w/m^2] | surface | Downward short-wave radiation flux reaching the surface. |
| 30. | DLWRF | downward long-wave rad. flux [w/m^2] | surface | Downward long-wave radiation flux reaching the surface. |
| 31. | USWRF | upward short-wave radiation flux [w/m^2] | surface | Upward short-wave radiation flux to the atmosphere. |
| 32. | ULWRF | upward long-wave rad. flux [w/m^2] | surface | Upward long-wave radiation flux to the atmosphere. |
| 33. | 4LFTX | Best (4 layer) Lifted Index [C] | surface |
The lifted index (LI) is the temperature difference between the environment Te(p) and an air parcel lifted adiabatically Tp(p) at a given pressure height in the troposphere (lowest layer where most weather occurs) of the atmosphere, usually 500 hPa (mb). The temperature is measured in Celsius. When the value is positive, the atmosphere (at the respective height) is stable and when the value is negative, the atmosphere is unstable. LI is generally scaled as follows:
|
| 34. | LAND | Land Cover (0=sea, 1=land) [1 = true] | surface | Indication if this area is sea or land. |
| 35. | ICEC | Ice Cover [%] | surface | Percentage of the ice covered surface. |
| 36. | ICETMP | Ice Temperature [C] | surface | Temperature of the surface ice. |
gfswave-model
Timesteps
- Days 1-3: hourly (Timesteps 0, 1, 2, ..., 70, 71, 72)
- Days 4-10: 3-hourly (Timesteps 75, 78, 81, ..., 234, 237, 249
Variablen
| name | long name | level | description | |
| 1. | WIND | Wind Speed [m/s] | surface | Wind speed 10 m above the ground (noaa level is surface, but it´s the wind speed 10 m above the ground |
| 2. | WDIR | Wind Direction (from which blowing) [°] | surface | |
| 3. | UGRD | U-Component of Wind [m/s] | surface | |
| 4. | VGRD | V-Component of Wind [m/s] | surface | |
| 5. | HTSGW | Significant Height of Combined Wind Waves and Swell [m] | surface | |
| 6. | PERPW | Primary Wave Mean Period [s] | surface | |
| 7. | DIRPW | Primary Wave Direction [°] | surface | |
| 8. | WVHGT | Significant Height of Wind Waves [m] | surface | |
| 9. | SWELL | 1 in sequence Significant Height of Swell Waves [m] | 1 in sequence | |
| 10. | SWELL | 2 in sequence Significant Height of Swell Waves [m] | 2 in sequence | |
| 11. | SWELL | 3 in sequence Significant Height of Swell Waves [m] | 3 in sequence | |
| 12. | WVPER | Mean Period of Wind Waves [s] | surface | |
| 13. | SWPER | 1 in sequence Mean Period of Swell Waves [s] | 1 in sequence | |
| 14. | SWPER | 2 in sequence Mean Period of Swell Waves [s] | 2 in sequence | |
| 15. | SWPER | 3 in sequence Mean Period of Swell Waves [s] | 3 in sequence | |
| 16. | WVDIR | Direction of Wind Waves [°] | surface | |
| 17. | SWDIR | 1 in sequence Direction of Swell Waves [deg] | 1 in sequence | |
| 18. | SWDIR | 2 in sequence Direction of Swell Waves [deg] | 2 in sequence | |
| 19. | SWDIR | 3 in sequence Direction of Swell Waves [deg] | 3 in sequence |
rtofs_prog-model
Timesteps
- Days 1-8: 3-hourly (Timesteps 0, 3, 6, ..., 186, 189, 192)
Variablen
| name | long name | level | description | |
| 1. | WATPDENA | Water potential density anomaly [
kg/m³]
|
0.01 mb | |
| 2. | PRACTSAL | Practical Salinity [g/kg] | surface | |
| 3. | WTMP | Water Temperature [C] | surface | |
| 4. | UOGRD | U-Component of Current (eastward) [m/s] | surface | |
| 5. | VOGRD | V-Component of Current (northward) [m/s] | surface |
rtofs_ice-model
Timesteps
- Days 1-8: 3-hourly (Timesteps 0, 3, 6, ..., 186, 189, 192)
Variablen
| name | long name | level | description | |
| 1. | ICEC | Ice Cover [%] | surface | |
| 2. | ICETMP | Ice Temperature [C] | surface | |
| 3. | ICETK | Ice Thickness [m] | surface | |
| 4. | UICE | U-Component of Ice Drift [m/s] | surface | |
| 5. | VICE | V-Component of Ice Drift [m/s] | surface |
- You don't want to retrieve prepared graphics, but raw data that you either want to process further or present in a way that best suits your application?
- Would you like to retrieve a larger number of weather variables?
- Would you like to be able to retrieve more time steps per day and over a longer period of time?
If you answer "yes" to any of these questions, then the Weather API is right for you:
- You can easily retrieve raw weather data via the Weather API at the start address "https://weather.openportguide.org/api/"
- A detailed description with the possibility to test individual functions of the API can be found at "https://weather.openportguide.org/api/docs" or "https://weather.openportguide.org/api/redoc"
- Over 60 different weather variabless are currently available, depending on the weather model in hourly time steps for the first three days and steps of three hours for days 4-10.
- The values of the data grid, interpolated values for each position, the values as an array for an entire area or any combination of weather variabless for any location and a freely selectable combination of time steps can be selected.