PHARES demo API

Swagger - Interactive API documentation and demonstration

See /api/docs

Available Endpoints

Direct access links to all active API endpoints. Required query parameters are indicated where applicable.

• List available storage zones
  Retrieves a list of all pre-configured storage zones. One storage zone is for example data from one forecasting chain. Each zone includes its name and description. Use this to identify from where you can download data.
  GET https://api-demo.phares-agrhymet.cilss.int/api/storage/list Copy
• Browse zone contents
  Lists all files and subdirectories within a specific storage zone. Supports an optional folder query parameter to navigate nested directories.
  GET https://api-demo.phares-agrhymet.cilss.int/api/storage/list/{zone_name}?folder=optional Copy
  • - zone_name (path param): The name of the storage zone
  • - folder (optional): Optional subfolder path inside the zone
• Download file or folder
  Downloads a specific file directly or a set of files in a folder. To download a folder, provide a directory path instead of a file path. Then the API automatically bundles the contents into a ZIP archive for a single-stream download. Supports deep path traversal within the zone.
  GET https://api-demo.phares-agrhymet.cilss.int/api/storage/download/{zone_name}/{file_path:path} Copy
  • - zone_name (path param): The name of the storage zone
  • - file_path (path param): The relative path to the file or folder
• Find latest data
  Scans the specified zone and returns the relative path to the most recent files. Useful for automated pipelines that only need to process the latest forecast data. With this function one can easily check which data is the latest available.
  GET https://api-demo.phares-agrhymet.cilss.int/api/storage/latest/list/{zone_name} Copy
  • - zone_name (path param): The name of the storage zone
• Download latest data
  Scans the specified zone and identifies most recent files in the zone and downloads them as a compressed ZIP-file. Useful for automated pipelines that only need to process the latest forecast data. With this function one can easily get the latest data files.
  GET https://api-demo.phares-agrhymet.cilss.int/api/storage/latest/download/{zone_name} Copy
  • - zone_name (path param): The name of the storage zone
• Generate map
  Shell endpoint that resolves paths and calls the unified spatial logic engine.
  GET https://api-demo.phares-agrhymet.cilss.int/api/visualize/map/{zone_name}/visualize?file_path=optional&variable=optional&shapefile_zone=optional&shapefile_path=optional&nc_id_col=optional&shp_id_col=optional&time_start_idx=optional&time_end_idx=optional&method=optional&cmap=optional&country=optional&bbox=optional&dpi=optional Copy
  • - zone_name (path param): The name of the storage zone
  • - file_path (optional): The relative path to the file
  • - variable (optional): The NetCDF variable to plot
  • - shapefile_zone (optional): Zone where the shapefile is stored. Defaults to zone_name automatically.
  • - shapefile_path (optional): Relative path to the .shp file
  • - nc_id_col (optional): Name of the variable containing the catchment IDs in the NetCDF file. Defaults to id
  • - shp_id_col (optional): Name of the column in the shapefile attribute table containing the catchment IDs. Defaults to ID
  • - time_start_idx (optional): The index of the first time step. Default is 0
  • - time_end_idx (optional): The index of the last time step of interest in producing the plot. Default is the index of the last time step in the NetCDF file.
  • - method (optional): To handle multiple time steps (i.e. between time_start_idx and time_end_idx), you must select a method to aggregate the data. Choose e.g. “last” to plot the last time step (i.e. time_end_idx), or “max” to plot the maximum value within the time range.
  • - cmap (optional): Name of the color map according to Matplotlib https://matplotlib.org/stable/users/explain/colors/colormaps.html. Use matplotlib, custom_ or .xml cmaps e.g. (cout_AL_QC-polygon.xml)
  • - country (optional): ISO 3166 alpha-3 code to filter by country. https://www.iban.com/country-codes
  • - bbox (optional): Spatial filter format: min_lon,min_lat,max_lon,max_lat
  • - dpi (optional): Image resolution (100-500)
• List available template variables
  Returns a dictionary of all variables available for the Word template.
  GET https://api-demo.phares-agrhymet.cilss.int/api/bulletin/schema Copy
• Generate Hydrological Bulletin
  Reads spatial data, generates a map, and renders a Word document bulletin.
  GET https://api-demo.phares-agrhymet.cilss.int/api/bulletin/generate/{zone_name}/bulletin?file_path=optional&variable=optional&title=optional&notes=optional&country=optional&bbox=optional&template_zone=optional&template_name=optional&cmap=optional&shapefile_zone=optional&shapefile_path=optional&nc_id_col=optional&shp_id_col=optional&time_start_idx=optional&time_end_idx=optional&method=optional&dpi=optional Copy
  • - zone_name (path param): The name of the storage zone
  • - file_path (optional): The relative path to the file
  • - variable (optional): The NetCDF variable to plot
  • - title (optional): Title for the report
  • - notes (optional): Optional notes in the bulletin.
  • - country (optional): Option to filter plotting to only show a specific country. Enter the ISO 3166 alpha-3 code of the country (https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes)
  • - bbox (optional): Spatial filter format: min_lon,min_lat,max_lon,max_lat
  • - template_zone (optional): Zone where the docx template is stored
  • - template_name (optional): Filename of the docx template
  • - cmap (optional): Name of the color map according to Matplotlib https://matplotlib.org/stable/users/explain/colors/colormaps.html. Use matplotlib, custom_ or .xml cmaps e.g. (cout_AL_QC-polygon.xml)
  • - shapefile_zone (optional): Defaults to zone_name
  • - shapefile_path (optional): Relative path to the .shp file
  • - nc_id_col (optional): Name of the variable containing the catchment IDs in the NetCDF file. Defaults to id
  • - shp_id_col (optional): Name of the column in the shapefile attribute table containing the catchment IDs. Defaults to ID
  • - time_start_idx (optional): The index of the first time step. Default is 0
  • - time_end_idx (optional): The index of the last time step of interest in producing the plot. Default is the index of the last time step in the NetCDF file.
  • - method (optional): To handle multiple time steps (i.e. between time_start_idx and time_end_idx), you must select a method to aggregate the data. Choose e.g. “last” to plot the last time step (i.e. time_end_idx), or “max” to plot the maximum value within the time range.
  • - dpi (optional): Image resolution (100-500)