Skip to content

WebAPI AClimate v3 API

Container: Python 3.10, FastAPI

The main API exposes the platform's data and services through RESTful endpoints. It is organized into the following modules:

Authentication / Authorization

Controls access to all API requests. Each request includes a JWT token generated by Keycloak when the user logs in. This module validates that token to confirm the user's identity and checks their permissions before allowing access to the requested data.

Responsibilities

  • Validate JWT tokens on every API request
  • Determine the user's access level based on their assigned roles
  • Restrict access to protected endpoints

Key functionalities detailed:

  1. Token validation — Validates the JWT signature and expiration against Keycloak's public keys.
  2. Permission checks — Verifies that the authenticated user has the required role to access the requested resource.
  3. Error responses — Returns standardized 401 (Unauthorized) and 403 (Forbidden) responses when authentication or authorization fails.

Admin levels

Provides the administrative geographic structure of each country. This includes countries, first-level divisions such as departments or states, and second-level divisions like municipalities. All weather stations, indicators, and forecasts in the platform are linked to this geographic hierarchy.

Responsibilities

  • Expose endpoints for querying geographic levels
  • Return the geographic hierarchy associated with each location
  • Support filtering by country and administrative division

Key functionalities detailed:

  1. Countries — List and query countries configured in the system.
  2. First-level divisions — Query administrative divisions such as departments or states for a given country.
  3. Second-level divisions — Query divisions such as municipalities for a given first-level division.

Locations

Manages weather stations and observation points. This module handles queries by station name, code, or geographic coordinates, and provides the associated metadata such as latitude, longitude, altitude, and data source.

Responsibilities

  • Support queries of stations by name, identifier, or geographic coordinates
  • Provide station metadata including geographic position and data source
  • Indicate whether a station has available data

Key functionalities detailed:

  1. Location search — Search stations by name or external code.
  2. Location details — Return full metadata for a station, including coordinates and source.
  3. Locations with data — Return stations that have climate data recorded in a recent period.

Climate Historical Monthly

Serves monthly aggregated climate data. After daily observations are processed and aggregated, this module makes the monthly values available for each location and climate measure.

Responsibilities

  • Expose monthly climate values for stations
  • Support filtering by location, date range, and climate measure
  • Return aggregated data in a standardized format

Key functionalities detailed:

  1. Monthly data queries — Retrieve monthly values for one or more locations.
  2. Date range filtering — Filter monthly data between a start and end date.
  3. Min/max values — Return the minimum and maximum monthly values recorded for each measure at a location.

Climate Historical Climatology

Provides climatological averages computed from historical records. These are long-term mean values per month and climate measure that represent the expected conditions at each station, useful as a reference for comparison.

Responsibilities

  • Serve climatological normal values per station and per month
  • Support queries by month range and location
  • Provide reference values for anomaly detection

Key functionalities detailed:

  1. Climatology queries — Retrieve average values per month for one or more locations.
  2. Month range filtering — Filter climatology data between a start and end month.
  3. Min/max climatology — Return the months with minimum and maximum climatological values for each measure.

Climate Historical Indicator

Serves derived climate indicators calculated from historical data, such as consecutive dry days and accumulated precipitation. These indicators summarize complex climate patterns into values that are easier to interpret.

Responsibilities

  • Expose climate indicator values for stations
  • Support filtering by location and date period
  • Return indicator metadata including name and unit

Key functionalities detailed:

  1. Indicator queries — Retrieve indicator values for a specific location.
  2. Location and period filtering — Filter indicators by location, date range, and period type.

Indicators

Provides the catalog of climate indicators available in the platform. It includes the definition of each indicator, its category, and the configuration associated with it.

Responsibilities

  • Expose the catalog of climate indicators
  • Provide indicator categories and features
  • Support filtering by category

Key functionalities detailed:

  1. Indicator catalog — List available indicators with their definitions.
  2. Categories — Group indicators by functional category.
  3. Features — Return the features associated with a country indicator.

Climate Historical Daily

Serves the daily climate records for each station, including temperature, precipitation, and other measures for specific dates. This is the most detailed level of data and serves as the base for all other aggregates and indicators.

Responsibilities

  • Expose daily climate observations for stations
  • Support filtering by location, date range, and climate measure
  • Provide min/max daily values for analysis

Key functionalities detailed:

  1. Daily data queries — Retrieve daily values for multiple locations.
  2. Date range filtering — Filter daily data between a start and end date.
  3. Min/max values — Return the dates with minimum and maximum daily values for each measure.

GeoServer

Connects the API with GeoServer to access spatial raster data. It allows extracting values from climate layers at specific coordinates and exporting raster data for offline analysis.

Responsibilities

  • Access spatial raster data through GeoServer
  • Extract point values from climate layers at given coordinates
  • Export raster data as GeoTIFF or ZIP archives

Key functionalities detailed:

  1. Point data extraction — Get climate values from a raster layer at specific coordinates and dates.
  2. Raster export — Export one or more raster layers within a date range as GeoTIFF files, optionally clipped to a geographic area.

Country Climate Measures

Defines which climate measures are available for each country. Not all measures are relevant in all regions, so this module determines which variables are exposed for each geographic area.

Responsibilities

  • Define the climate measures available per country
  • Determine which variables are published for each region
  • Support configuration of spatial and location data availability

Key functionalities detailed:

  1. Country measure queries — Retrieve the measures configured for a specific country.

For installation instructions, refer to the README in the repository: github.com/CIAT-DAPA/aclimate_v3_webapi