Usage¶
Using ogd_api
to access ICON-CH1/2-EPS forecasts¶
The ogd_api
module provides a Python interface to the STAC search API on data.geo.admin.ch.
It enables querying and retrieving numerical weather prediction (NWP) data from MeteoSwiss, published through Switzerland’s Open Government Data (OGD) initiative and extended for forecast-specific access.
You can find interactive Jupyter notebooks demonstrating the usage of ogd_api
here: MeteoSwiss Open Data NWP Demos.
This example walks you through creating requests and retrieving forecast data.
Step 1: Build requests¶
Use ogd_api.Request
to define a query, for example, to retrieve ICON-CH2-EPS total precipitation.
from datetime import datetime, timezone
from meteodatalab import ogd_api
req = ogd_api.Request(
collection="ogd-forecasting-icon-ch2",
variable="TOT_PREC",
reference_datetime="latest",
perturbed=False,
horizon=f"P0DT2H"
)
Each argument in the request serves the following purpose:
Argument |
Description |
---|---|
|
Forecast collection to use. Examples:
|
|
Meteorological variable of interest. Example: |
|
Initialization time of the forecast in UTC, provided as one of the following:
|
|
If |
|
Forecast lead time, provided as one of the following:
|
Step 2: Retrieve forecasts¶
To access the forecast data, you have two choices:
Load forecast data to Xarray with
get_from_ogd
Download forecast data with
download_from_ogd
1. Load forecast data to Xarray
We now send our request to the API and retrieve the resulting dataset using the get_from_ogd
function. The response is returned as an xarray.DataArray
, which is efficient for handling multi-dimensional data.
Hint
You can use configure caching behaviour in earthkit-data to avoid re-downloading files:
"off"
(default): no caching — files are always freshly downloaded"temporary"
: auto-cleared after the session"user"
: saves to a specific directory across sessions
See the earthkit-data caching documentation for more details.
from earthkit.data import config
# Enable temporary cache
config.set("cache-policy", "temporary")
# Load data as xarray.DataArray
da = ogd_api.get_from_ogd(req)

2. Download forecast data
from pathlib import Path
# Define the target directory for saving the forecast files
target_dir = Path.cwd() / "forecast_files"
# Download the forecast files
ogd_api.download_from_ogd(req, target_dir)
# List all downloaded files in the target directory
print("Downloaded files:")
for file in sorted(target_dir.iterdir()):
print(f" - {file.name}")
After downloading, you should find the following files inside the forecast_files/
directory:
horizontal_constants_icon-ch2-eps.grib2
horizontal_constants_icon-ch2-eps.sha256
icon-ch2-eps-<today's-datetime>-2-tot_prec-ctrl.grib2
icon-ch2-eps-<today's-datetime>-2-tot_prec-ctrl.sha256
vertical_constants_icon-ch2-eps.grib2
vertical_constants_icon-ch2-eps.sha256
Warning
Missing grid coordinates
Forecast GRIB files like icon-ch2-eps-*.grib2
do not include horizontal or vertical coordinates (longitude, latitude, or height).
Therefore, the horizontal and vertical constants are provided as separate files to fully describe the forecast grid. This applies when using
download_from_ogd
. If you use get_from_ogd
, the horizontal coordinates are automatically loaded
and included as part of the xarray.DataArray
.
Hint
Checksum verification
During the download, each file’s integrity is verified using a SHA-256 checksum provided via HTTP headers.
These checksums are saved as .sha256
files and used to skip re-downloading valid existing files.
Learn more about the data structure here.