Context
WEkEO provides access to a wide range of Earth observation datasets through the WEkEO catalogue. While the Expert Data Viewer is a great tool for exploring and visualising data, it is limited when it comes to downloading large amounts of data programmatically. The HDA Python package is the right tool for this, and normally, using it requires installing Python and the hda package on your machine.
With the WEkEO JupyterHub, none of that is needed. The environment is ready to use directly in your browser: the hda package is pre-installed, and you can start downloading data in minutes with no setup whatsoever.
With a few lines of code in a notebook, you can submit a query and download all matching results in one single operation, directly within your JupyterHub environment.
🔍 For a more complete introduction to the HDA API, please refer to: What is the Harmonized Data Access (HDA) API?
💡 WEkEO Pro Tip: to use the HDA service, you must first register for a WEkEO account.
Step by step guide
Step 1. Access the WEkEO JupyterHub
Sign in to your WEkEO account and go to your MyWEkEO dashboard. Click Open next to WEkEO Workspace, then sign in with OAuth 2.0 and enter the verification code sent to your email.
On the Server Options screen, select Earth Observation Tools and click Start.
💡 WEkEO Pro Tip: the Earth Observation Tools environment includes the hda package pre-installed, no additional setup is required!
🔍 For detailed access instructions, please refer to: What is the WEkEO JupyterHub?
Step 2. Create your working folder and a new notebook
Once JupyterHub has loaded, you will see the file browser on the left panel.
Create a personal folder: right-click in the file browser → New Folder, and give it a name (e.g.
MyWork). This keeps your files separate from the sharedpublicfolder.
Open your folder by double-clicking on it.
Create a new notebook: the Launcher tab opens by default when JupyterHub starts. If it is not visible, click the + button in the top-left to open it. Under Notebook, select Python 3 (ipykernel) or hda.
Check the kernel shown in the top-right corner of the notebook: it should display Python (ipykernel) or wekeolab. If not, click on it and select the correct one.
💡 WEkEO Pro Tip: Prefer a ready-to-use example? Download the notebook below and drag it from your computer into your personal folder in the JupyterHub file browser. Then open it and run the cells in order.
⚠️ Under your home directory, up to 20 GB of storage are available.
Step 3. Import the hda module and configure credentials
In the first cell of your notebook, import the needed functions and connect to the HDA using your WEkEO credentials:
from hda import Client, Configuration
import shutil
# Replace with your WEkEO username and password
conf = Configuration(user="xxxx", password="xxxx")
hda_client = Client(config=conf)
💡 WEkEO Pro Tip: use the same credentials you use to log in to wekeo.copernicus.eu.
Step 4. Define your query
The query is a JSON object that describes the data you want to download: which dataset, which geographic area, which filters (date, product type, resolution…).
The recommended way to build it is directly from the Expert Data Viewer, which lets you visually set your filters and verify that results are returned before copying the query.
🔍 To learn how to build and copy your query from the Viewer, please refer to: How to download data through WEkEO?
Once copied, paste it in the second cell of your notebook. Here is an example for the Global Ocean Physics Analysis and Forecast dataset:
query = {
"dataset_id": "EO:MO:DAT:GLOBAL_ANALYSISFORECAST_PHY_001_024:cmems_mod_glo_phy-so_anfc_0.083deg_P1D-m_202406",
"minimum_depth": 0.494024992,
"maximum_depth": 100,
"startdate": "2026-06-01T00:00:00.000Z",
"enddate": "2026-06-07T23:59:59.999Z",
"bbox": [
4.3595919567022055,
41.893317734758384,
5.561835484362211,
42.60122926047297
],
"variables": [
"so"
],
"itemsPerPage": 200,
"startIndex": 0
}💡 WEkEO Pro Tip: always build and test your query in the Viewer first, this ensures it returns results before you run the download.
Step 5. Search and download
In the third cell, run the search and download the matching files:
# Search for files matching the query
matches = hda_client.search(query)
# List the results
print(matches)
# Download all results into a directory
download_dir = "data"
matches.download(download_dir=download_dir)
The hda_client.search(query) function performs the search and stores the results in matches. The .download() function then downloads all matching files in one batch to the specified directory.
# Zip the download directory
shutil.make_archive("my_data", "zip", ".", download_dir)
shutil.make_archive() compresses the download_dir folder into a my_data.zip file, saved alongside your notebook and data folder.
Once the archive is created, see the Saving files to your local machine section below to download it to your computer.
Saving files to your local machine
The my_data.zip file will appear in the file browser, in your personal folder. To download it to your computer:
In the file browser on the left, locate the
my_data.zipfile in your personal folder.Right-click on it → Download.
The zip file will be saved locally to the location of your choice.
And that's it!
You can now download WEkEO data directly from the JupyterHub using the HDA API! 🙌
Downloading more than 20 GB
If the files you need to download exceed your 20 GB personal storage, replace the download_dir line with the shared temporary folder:
download_dir = ("/home/jovyan/processing-results/")⚠️ Important: processing-results is a shared, non-persistent directory. It is not backed up and can be cleared at any time without prior notice. Use it only as a temporary workspace, and make sure to download your files locally as soon as your processing is complete.
What's next?
Additional resources can be found in our Help Center. Should you require further assistance or wish to provide feedback, feel free to contact us through a chat session available in the bottom right corner of the page.