Skip to content

APIs for data access

Jump to bottom
Jafet Andersson edited this page May 20, 2026 · 24 revisions

PHARES APIs

The following Application Programming Interfaces (APIs) are available to access forecasts data from different forecasting chains in PHARES.

Name Access Geographic domain Status Link
Demo Open West Africa and Sahel Selected dates http://api-demo.phares-agrhymet.cilss.int/
WAS Restricted West Africa and Sahel Operational data https://api-was.phares-agrhymet.cilss.int/
BFA Restricted Burkina Faso Operational data https://api-bfa.phares-agrhymet.cilss.int/

Access

Data structure, folders and files

Each API contains data for one or more storage zones, i.e. one zone for each forecasting chain in the geographic domain, and an additional storage zone for bulletin templates. In each forecasting chain the data is structured into folders and then individual files. These data, folders and files depend on the forecasting system which the forecasting chain belongs to, which is presented separately below.

FANFAR system

For the FANFAR-related forecasting chains data is structured in the following types of folders:

  1. One folder with static data for the selected forecast chain. This folder is named _static.
  2. One folder for each day a forecast has been produced (the forecast issue date). These are named by the date, i.e. YYYYMMDD, e.g. 20260510
  3. One folder containing the latest available forecasts, named latest.

The following files are available in the folder with static data (no. 1)

  • subbasins_pourpoint_coordinates.shp: Shapefile with polygons of subbasins (catchments) in the hydrological model HYPE.
  • stations-cout.gpkg: GeoPackage file with points showing the locations of hydrometric stations in the hydrological model HYPE.
  • thresholds-al-cout.txt: Textfile containing the flood hazard alert level thresholds ("al") for discharge ("cout") from the HYPE model, for each subbasin. Note "alert level" and "severity level" are used interchangeably.

The following files are available in the folders for a specific forecast issue date (no. 2)

  • One NetCDF file containing data for the forecast time period (1 to 10 day forward starting from the forecast issue date). The name of the file follows the following convention: forecast_YYYY-MM-DDRX.nc, where YYYY is year, MM is month, DD is day, and RX is the revision number of the file. For example forecast_2026-05-10R1.nc means the file contains data for the forecast issued on 2026-05-10 and for the forecast period. R1 means that it is the first version of the file (i.e. it has not been changed after being produced once).
  • One NetCDF file containing data for dates immediately before the forecast issue date, i.e. the analysis period used to initialize the model. The name of the file follows the following convention: analysis_YYYY-MM-DDRX.nc, where YYYY is year, MM is month, DD is day, and RX is the revision number of the file. For example analysis_2026-05-10R2.nc means the file contains data for the forecast issued on 2026-05-10 for the analysis period. R2 means that it is the second version of the file (i.e. it has been changed once after being produced initially).

The NetCDF files have dimensions time and id, where id corresponds to the subbasin id in subbasins_pourpoint_coordinates.shp and stations-cout.gpkg. the NetCDF files contain a number of variables. The most important are the following:

  • cout: HYPE variable for simulated streamflow (discharge, m3/s), at the outlet of each subbasin.
  • cout_AL_QC: Streamflow categorized into alert levels (AL) based on flood hazard thresholds. Valid at the outlet of each subbasin. Note "alert level" and "severity level" are used interchangeably. QC means that for some subbasins (mainly dry areas), the threshold method (return periods estimated by GEV) is not able to define thresholds accurately ("Disqualified alert levels").
  • cout_AL: Streamflow categorized into alert levels (AL) based on flood hazard thresholds. Unlike cout_AL_QC, this variable is not filtered for cases where the threshold method is inaccurate.
  • cout_AL_thresholds_1, cout_AL_thresholds_2 and cout_AL_thresholds_3: threshold values used to categorize streamflow when creating cout_AL_QC and cout_AL
  • cprc: HYPE variable for precipitation (mm/day) in each subbasin.
  • upcprc: HYPE variable for upstream precipitation, i.e. the area-weighted averaage precipitation in the entire upstream area of the catchment above the selected subbasin (mm/day).
  • cros: HYPE variable for surface runoff (mm/day) in each subbasin.
  • evap: HYPE variable for actual evaporation (mm/day) in each subbasin.
  • corl: HYPE variable for water level of the river at the outlet of the subbasin (m above global reference, usually sea level) Available only in selected subbasins where a rating curve is present.
  • crrl: HYPE variable for water level of the river at the outlet of the subbasin. Here the unit is in the local reference system, usually cm above local reference, typically the zero-level of a local gauge. crrl is available only in selected subbasins where a rating curve is present.

The following files are available in the folder latest (no. 3)

  • NetCDF files for the latest forecast issue date. A copy of the forecast*.nc and analysis*.nc files for the latest date

Notes regarding specific API endpoints

Visualisation > Generate map

  • Once you have selected a variable (see list above) you should use an appropriate color map (cmap) that fits with this variable. For continous variables, use continuous color maps; and for categorical variables use categorical colour maps.
  • For the variable cout_AL_QC, we recommend to use the custom color map that shows the categories in the same way as on the visualisation portal. I.e. use cout_AL_QC-polygon.xml as cmap.

Exercises

logos

PHARES Wiki Pages

English

Francais

Search

Search wiki

Clone this wiki locally