Exercise 02 Data Extraction and Processing with FastAPI

1. Objective

The objective of this exercise is to help participants understand how to use the PHARES API services to access, download and process forecast data for operational use. By the end of the exercise, participants should be able to:

• explore available API endpoints;
• identify available storage zones;
• browse forecast data directories;
• download selected files or folders;
• retrieve the latest forecast data;
• generate a map from selected forecast data;
• understand how API outputs can support bulletin production.

2. Access to the API

Open the PHARES demo API page:

• Demo API docs
• Demo API

3. Main API Functionalities

The PHARES API provides several operational functionalities:

• Data access: List and download forecast data from storage zones
• Visualization: Generate maps from selected forecast files
• Bulletin: Generate draft hydrological bulletins from selected data

4. Practical Tasks

• Task 1 – Explore Available Storage Zones
• Task 2 – Browse the Content of a Storage Zone
• Task 3 – Download a Specific File or Folder
• Task 4 – Retrieve the Latest Forecast Data
• Task 5 – Generate a Map from Forecast Data
• Task 6 – Understand Bulletin Generation

Task 1 – Explore Available Storage Zones

Use the endpoint: GET /api/storage/list

Expected action:

• open the endpoint in the browser or Swagger;
• list the available storage zones ;
• identify the storage zone corresponding to the forecast data.

Questions :

• Which storage zones are available?
• What type of forecast chain does each zone represent?

Task 2 – Browse the Content of a Storage Zone

Use the endpoint: GET /api/storage/list/{zone_name}

Expected action :

• select one storage zone;
• browse its files and folders;
• identify available forecast outputs.

Questions:

• What folders or files are available?
• Can you identify NetCDF files or other forecast products?

Task 3 – Download a Specific File or Folder

Use the endpoint: GET /api/storage/download/{zone_name}/{file_path}

Expected action:

• select one storage zone
• select a file path;
• download it locally;
• verify the downloaded content.

Questions:

• What type of file did you download?
• Is the file directly usable for analysis or does it require processing?

Task 4 – Retrieve the Latest Forecast Data

Use one of the following endpoints:

• GET /api/storage/latest/list/{zone_name}
• GET /api/storage/latest/download/{zone_name}

Expected action:

• identify the latest available forecast data;
• download the latest forecast package if needed. Questions:
• What is the latest forecast date available?
• How could this endpoint support an automated operational workflow?

Task 5 – Generate a Map from Forecast Data

Use the endpoint: GET /api/visualize/map/{zone_name}/visualize

Expected action:

• select a forecast file;
• choose the variable to visualize;
• optionally filter by country using the ISO 3166 alpha-3 country code;
• generate a map. Important parameters include:
• zone_name : Name of the storage zone
• file_path : Relative path to the forecast file
• variable : NetCDF variable to plot
• country : Country filter using ISO 3166 alpha-3 code
• bbox : Spatial filter: min_lon,min_lat,max_lon,max_lat
• method : Aggregation method for multiple time steps, for example last or max
• dpi : Image resolution

Questions:

• Which variable did you visualize?
• Which country or area did you select?
• Does the generated map help identify flood-risk areas?

Task 6 – Understand Bulletin Generation

Use the endpoint: GET /api/bulletin/generate/{zone_name}/bulletin

Expected action:

• review the required and optional parameters;
• understand how the API can generate a draft Word bulletin;
• identify which parameters are needed for operational bulletin production.

Questions:

• Which inputs are required to generate a bulletin?
• How can this functionality support national hydrological services?
• What types of forecast products or maps could be integrated into the generated bulletin?