WebAPI AClimate v3 API¶
Contenedor: Python 3.10, FastAPI
La API principal expone los datos y servicios de la plataforma mediante endpoints RESTful. Está organizada en los siguientes módulos:
Authentication / Authorization¶
Controla el acceso a todas las solicitudes de la API. Cada solicitud incluye un token JWT generado por Keycloak cuando el usuario inicia sesión. Este módulo valida ese token para confirmar la identidad del usuario y verifica sus permisos antes de permitir el acceso a los datos solicitados.
Responsabilidades
- Validar tokens JWT en cada solicitud a la API
- Determinar el nivel de acceso del usuario según sus roles asignados
- Restringir el acceso a endpoints protegidos
Funcionalidades clave detalladas:
- Validación de token — Valida la firma y expiración del JWT contra las claves públicas de Keycloak.
- Verificación de permisos — Verifica que el usuario autenticado tenga el rol requerido para acceder al recurso solicitado.
- Respuestas de error — Retorna respuestas estandarizadas 401 (No autorizado) y 403 (Prohibido) cuando falla la autenticación o autorización.
Admin levels¶
Proporciona la estructura geográfica administrativa de cada país. Esto incluye países, divisiones de primer nivel como departamentos o estados, y divisiones de segundo nivel como municipios. Todas las estaciones meteorológicas, indicadores y pronósticos de la plataforma están vinculados a esta jerarquía geográfica.
Responsabilidades
- Exponer endpoints para consultar niveles geográficos
- Retornar la jerarquía geográfica asociada a cada ubicación
- Soportar filtrado por país y división administrativa
Funcionalidades clave detalladas:
- Países — Listar y consultar los países configurados en el sistema.
- Divisiones de primer nivel — Consultar divisiones como departamentos o estados para un país.
- Divisiones de segundo nivel — Consultar divisiones como municipios para una división de primer nivel.
Locations¶
Gestiona las estaciones meteorológicas y puntos de observación. Este módulo maneja consultas por nombre de estación, código o coordenadas geográficas, y proporciona los metadatos asociados como latitud, longitud, altitud y fuente de datos.
Responsabilidades
- Soportar consultas de estaciones por nombre, identificador o coordenadas geográficas
- Proporcionar metadatos de estación incluyendo posición geográfica y fuente de datos
- Indicar si una estación tiene datos disponibles
Funcionalidades clave detalladas:
- Búsqueda de ubicaciones — Buscar estaciones por nombre o código externo.
- Detalles de ubicación — Retornar metadatos completos de la estación, incluyendo coordenadas y fuente.
- Ubicaciones con datos — Retornar estaciones que tienen datos climáticos registrados en un período reciente.
Climate Historical Monthly¶
Sirve datos climáticos mensuales agregados. Después de que las observaciones diarias se procesan y agregan, este módulo pone a disposición los valores mensuales para cada ubicación y medida climática.
Responsabilidades
- Exponer valores climáticos mensuales para estaciones
- Soportar filtrado por ubicación, rango de fechas y medida climática
- Retornar datos agregados en un formato estandarizado
Funcionalidades clave detalladas:
- Consultas de datos mensuales — Obtener valores mensuales para una o más ubicaciones.
- Filtrado por rango de fechas — Filtrar datos mensuales entre una fecha inicial y final.
- Valores mínimos/máximos — Retornar los valores mensuales mínimos y máximos registrados para cada medida en una ubicación.
Climate Historical Climatology¶
Proporciona los promedios climatológicos calculados a partir de registros históricos. Son valores medios de largo plazo por mes y medida climática que representan las condiciones esperadas en cada estación, útiles como referencia para comparaciones.
Responsabilidades
- Servir valores normales climatológicos por estación y por mes
- Soportar consultas por rango de meses y ubicación
- Proporcionar valores de referencia para detección de anomalías
Funcionalidades clave detalladas:
- Consultas de climatología — Obtener valores promedio por mes para una o más ubicaciones.
- Filtrado por rango de meses — Filtrar datos climatológicos entre un mes inicial y final.
- Climatología mínima/máxima — Retornar los meses con valores climatológicos mínimos y máximos para cada medida.
Climate Historical Indicator¶
Sirve los indicadores climáticos derivados calculados a partir de datos históricos, como días secos consecutivos y precipitación acumulada. Estos indicadores resumen patrones climáticos complejos en valores más fáciles de interpretar.
Responsabilidades
- Exponer valores de indicadores climáticos para estaciones
- Soportar filtrado por ubicación y período de fechas
- Retornar metadatos de indicadores incluyendo nombre y unidad
Funcionalidades clave detalladas:
- Consultas de indicadores — Obtener valores de indicadores para una ubicación específica.
- Filtrado por ubicación y período — Filtrar indicadores por ubicación, rango de fechas y tipo de período.
Indicators¶
Proporciona el catálogo de indicadores climáticos disponibles en la plataforma. Incluye la definición de cada indicador, su categoría y la configuración asociada.
Responsabilidades
- Exponer el catálogo de indicadores climáticos
- Proporcionar categorías y características de los indicadores
- Soportar filtrado por categoría
Funcionalidades clave detalladas:
- Catálogo de indicadores — Listar indicadores disponibles con sus definiciones.
- Categorías — Agrupar indicadores por categoría funcional.
- Características — Retornar las características asociadas a un indicador de país.
Climate Historical Daily¶
Sirve los registros climáticos diarios de cada estación, incluyendo temperatura, precipitación y otras medidas para fechas específicas. Es el nivel de datos más detallado y sirve como base para todos los demás agregados e indicadores.
Responsabilidades
- Exponer observaciones climáticas diarias para estaciones
- Soportar filtrado por ubicación, rango de fechas y medida climática
- Proporcionar valores diarios mínimos/máximos para análisis
Funcionalidades clave detalladas:
- Consultas de datos diarios — Obtener valores diarios para múltiples ubicaciones.
- Filtrado por rango de fechas — Filtrar datos diarios entre una fecha inicial y final.
- Valores mínimos/máximos — Retornar las fechas con valores diarios mínimos y máximos para cada medida.
GeoServer¶
Conecta la API con GeoServer para acceder a datos raster espaciales. Permite extraer valores de las capas climáticas en coordenadas específicas y exportar datos raster para análisis fuera de línea.
Responsabilidades
- Acceder a datos raster espaciales a través de GeoServer
- Extraer valores puntuales de capas climáticas en coordenadas dadas
- Exportar datos raster como archivos GeoTIFF o ZIP
Funcionalidades clave detalladas:
- Extracción de datos puntuales — Obtener valores climáticos de una capa raster en coordenadas y fechas específicas.
- Exportación raster — Exportar una o más capas raster en un rango de fechas como archivos GeoTIFF, opcionalmente recortadas a un área geográfica.
Country Climate Measures¶
Define qué medidas climáticas están disponibles para cada país. No todas las medidas son relevantes en todas las regiones, por lo que este módulo determina qué variables se exponen para cada área geográfica.
Responsabilidades
- Definir las medidas climáticas disponibles por país
- Determinar qué variables se publican para cada región
- Soportar configuración de disponibilidad de datos espaciales y por ubicación
Funcionalidades clave detalladas:
- Consultas de medidas por país — Obtener las medidas configuradas para un país específico.
Para instrucciones de instalación, consultar el README del repositorio: github.com/CIAT-DAPA/aclimate_v3_webapi