Skip to content

04. API (WebAPI)

The WebAPI is a Python FastAPI application (title: "Aclimate v3 API", version 3.0) that exposes RESTful endpoints organized by functional domain. It uses the aclimate_v3_orm package for data access and provides JWT-based authentication via Keycloak.

Base URL

https://api.aclimate.org

The API documentation (Swagger UI) is available at https://api.aclimate.org/docs.

Authentication

The API uses JWT tokens via Keycloak. All endpoints (except health) require authentication.

Client Credentials Flow

POST /auth/client-token
Content-Type: application/json

{
    "client_id": "...",
    "client_secret": "..."
}

Response:

{
  "access_token": "eyJ...",
  "expires_in": 300,
  "token_type": "Bearer"
}

All subsequent requests include the token:

Authorization: Bearer <token>

Token Validation

POST /auth/validate-token
Authorization: Bearer <token>

API Domains

Domain Tags Description
Geographic Admin levels, Locations Countries, admin divisions, locations
Climate Climate Historical Daily/Monthly/Climatology/Indicator Historical climate data
Agronomic Indicators Indicators, categories, features
Auth Authentication Token management
Users Users User CRUD operations
Roles Roles Role management
GeoServer Geoserver Spatial data access
Health Health Service health checks

Endpoint Conventions

All endpoints return JSON responses. List endpoints support the following common patterns:

Response Format

{
  "id": 1,
  "name": "Colombia",
  "iso2": "CO"
}

Error Handling

Standard HTTP status codes:

  • 200: Success
  • 401: Unauthorized (missing/invalid token)
  • 403: Forbidden (insufficient permissions)
  • 404: Not Found
  • 422: Unprocessable Entity
  • 500: Internal Server Error

Error responses:

{
  "detail": "Error description"
}

Schemas

The API uses Pydantic schemas from schemas/ directory for request/response serialization. Key schemas include:

  • Country: id, name, iso2
  • Admin1: id, name, ext_id, country_id, country_name, country_iso2
  • Admin2: id, name, ext_id, admin1_id, admin1_name, country_id, country_name, country_iso2
  • Location: id, name, latitude, longitude, altitude, admin hierarchy, source
  • LocationWithData: Location + latest monitoring data with measures
  • MeasureData: measure_id, measure_name, measure_short_name, measure_unit, value
  • ClimateHistoricalDateRecord: location, measure, date, value
  • ClimateHistoricalMonthRecord: location, measure, month, value
  • ClimateHistoricalIndicatorRecord: indicator, location, value, period, date range
  • MinMaxMonthRecord / MinMaxDateRecord: min/max values per location

Health Endpoints

Endpoint Method Description
/health GET Liveness check (Docker HEALTHCHECK)
/ready GET Readiness check (Kubernetes probe, verifies DB)

The health endpoint returns {"status": "ok"} and the ready endpoint checks database connectivity, returning 200 if healthy or 503 if not.

Sections