Servicio de Información Meteorologica


📘 Introducción

Descripción

Este proyecto es una API de Clima Local implementada con Laravel 12, que ofrece un servicio RESTful para obtener información climática basada en coordenadas geográficas.

A diferencia de las soluciones que dependen de APIs externas, esta API consulta directamente una base de datos local que contiene registros históricos y precargados de datos climáticos.

La carga de datos en la base de datos se realiza mediante un proceso automatizado con N8N, el cual consulta periódicamente la API de CONAGUA y persiste la información localmente. La aplicación sigue principios de diseño limpio, utilizando Laravel Actions para la encapsulación de la lógica de negocio y Laravel API Resources para una transformación y presentación de datos consistente y limpia.

Objetivo

Proveer un servicio confiable y eficiente para la consulta de información climática basada en coordenadas geográficas, a través de una API RESTful construida con Laravel 12. Esta solución permite acceder a datos meteorológicos históricos y actualizados sin depender de fuentes externas, gracias a una base de datos local alimentada automáticamente desde la API de CONAGUA mediante N8N. El sistema garantiza respuestas consistentes y estructuradas, siguiendo principios de diseño limpio que facilitan su mantenimiento, escalabilidad e integración con otras aplicaciones o servicios institucionales.

Características Principales

Tecnologías Utilizadas

🔐 Autenticación

Actualmente, el servicio se encuentra accesible de forma abierta, sin requerimientos de autenticación, con el objetivo de facilitar su integración temprana y evaluación funcional.

No obstante, se contempla la implementación de un mecanismo de autenticación robusto en fases posteriores, orientado a controlar el acceso, registrar el consumo por usuario o sistema, y garantizar la seguridad de la información. Este mecanismo podría incluir autenticación mediante tokens (API Keys o JWT), adaptándose a las necesidades del entorno donde se integre el servicio.

🌐 Servicios Web

Entornos 

La API de Clima Local está disponible en los siguientes entornos:

Ambiente URL
Pruebas https://test-aplicaciones.tamaulipas.gob.mx/srv-clima/
Producción No disponible actualmente
Endpoints de la API

Todos los endpoints están disponibles bajo el prefijo:
/api/v1/

Enpoints disponibles
Método Endpoint Descripción
GET /api/v1/clima-actual Consulta el clima actual por coordenadas geográficas.
GET /api/v1/clima-pronostico Consulta el pronóstico del clima para los próximos días.
GET /api/v1/clima-pronostico/municipios Consulta el pronóstico del clima para los próximos días por municipios.


📡 GET /api/v1/clima-actual

Descripción

Consulta el clima actual en función de las coordenadas geográficas proporcionadas. Utiliza los datos más recientes disponibles en la base de datos local.

Parámetros esperados (query string)
Parámetro Tipo Requerido Descripción
latitud float Sí Latitud en formato decimal.
longitud float Sí Longitud en formato decimal.
Ejemplo de petición
GET /api/v1/clima-actual?latitud=23.731100&longitud=-99.151300
Ejemplo de respuesta exitosa (200 OK)
{
  "error": false,
  "status": 200,
  "message": "Clima actual obtenido correctamente.",
  "data": {
    "id_estado": 28,
    "id_municipio": 41,
    "nombre_estado": "Tamaulipas",
    "nombre_municipio": "Victoria",
    "dia_local": "2025-06-24 00:00:00",
    "numero_dia": 0,
    "temperatura_maxima_c": "31.70",
    "temperatura_minima_c": "18.90",
    "descripcion_cielo": "Poco nuboso",
    "probabilidad_precipitacion_porcentaje": 50,
    "precipitacion_litros_m2": "14.70",
    "velocidad_viento_kmh": "10.60",
    "direccion_viento_cardinal": "Sureste",
    "direccion_viento_grados": "135.00",
    "cobertura_nubes_porcentaje": "7.75",
    "latitud": "23.731100",
    "longitud": "-99.151300",
    "diferencia_utc": 6
  },
  "metadata": {
    "Organization": "Agencia de Innovación e Inteligencia Digital de Tamaulipas",
    "Department": "Departamento de Desarrollo de Soluciones Informáticas"
  }
}

🌦️ GET /api/v1/clima-pronostico

Descripción

Devuelve el pronóstico del clima para los próximos días en la ubicación indicada. La información se obtiene de registros meteorológicos precargados en una base de datos local.

Parámetros esperados (query string)
Parámetro Tipo Requerido Descripción
latitud float Sí Latitud en formato decimal.
longitud float Sí Longitud en formato decimal.
Ejemplo de petición
GET /api/v1/clima-pronostico?latitud=23.731100&longitud=-99.151300
Ejemplo de respuesta exitosa (200 OK)
{
  "error": false,
  "status": 200,
  "message": "Clima obtenido correctamente.",
  "data": [
    {
      "id_estado": 28,
      "id_municipio": 41,
      "nombre_estado": "Tamaulipas",
      "nombre_municipio": "Victoria",
      "dia_local": "2025-06-24 00:00:00",
      "numero_dia": 0,
      "temperatura_maxima_c": "31.70",
      "temperatura_minima_c": "18.90",
      "descripcion_cielo": "Poco nuboso",
      "probabilidad_precipitacion_porcentaje": 50,
      "precipitacion_litros_m2": "14.70",
      "velocidad_viento_kmh": "10.60",
      "direccion_viento_cardinal": "Sureste",
      "direccion_viento_grados": "135.00",
      "cobertura_nubes_porcentaje": "7.75",
      "latitud": "23.731100",
      "longitud": "-99.151300",
      "diferencia_utc": 6
    },
    {
      "id_estado": 28,
      "id_municipio": 41,
      "nombre_estado": "Tamaulipas",
      "nombre_municipio": "Victoria",
      "dia_local": "2025-06-25 00:00:00",
      "numero_dia": 1,
      "temperatura_maxima_c": "31.60",
      "temperatura_minima_c": "19.30",
      "descripcion_cielo": "Medio nublado",
      "probabilidad_precipitacion_porcentaje": 0,
      "precipitacion_litros_m2": "0.90",
      "velocidad_viento_kmh": "11.60",
      "direccion_viento_cardinal": "Sur",
      "direccion_viento_grados": "180.00",
      "cobertura_nubes_porcentaje": "63.76",
      "latitud": "23.731100",
      "longitud": "-99.151300",
      "diferencia_utc": 6
    },
    {
      "id_estado": 28,
      "id_municipio": 41,
      "nombre_estado": "Tamaulipas",
      "nombre_municipio": "Victoria",
      "dia_local": "2025-06-26 00:00:00",
      "numero_dia": 2,
      "temperatura_maxima_c": "31.10",
      "temperatura_minima_c": "19.20",
      "descripcion_cielo": "Medio nublado",
      "probabilidad_precipitacion_porcentaje": 10,
      "precipitacion_litros_m2": "1.60",
      "velocidad_viento_kmh": "8.80",
      "direccion_viento_cardinal": "Sureste",
      "direccion_viento_grados": "135.00",
      "cobertura_nubes_porcentaje": "60.21",
      "latitud": "23.731100",
      "longitud": "-99.151300",
      "diferencia_utc": 6
    },
    {
      "id_estado": 28,
      "id_municipio": 41,
      "nombre_estado": "Tamaulipas",
      "nombre_municipio": "Victoria",
      "dia_local": "2025-06-27 00:00:00",
      "numero_dia": 3,
      "temperatura_maxima_c": "31.80",
      "temperatura_minima_c": "19.00",
      "descripcion_cielo": "Cielo nublado",
      "probabilidad_precipitacion_porcentaje": 10,
      "precipitacion_litros_m2": "1.40",
      "velocidad_viento_kmh": "9.60",
      "direccion_viento_cardinal": "Sureste",
      "direccion_viento_grados": "135.00",
      "cobertura_nubes_porcentaje": "32.28",
      "latitud": "23.731100",
      "longitud": "-99.151300",
      "diferencia_utc": 6
    }
  ],
  "metadata": {
    "Organization": "Agencia de Innovación e Inteligencia Digital de Tamaulipas",
    "Department": "Departamento de Desarrollo de Soluciones Informáticas"
  }
}

 

 

🏘️ GET /api/v1/clima-pronostico/municipios

Descripción

Devuelve el pronóstico del clima para los próximos días de una lista de municipios específicos. La información se obtiene de registros meteorológicos precargados en una base de datos local.

Parámetros esperados (query string)
Parámetro Tipo Requerido Descripción
municipios string (comma-separated) or array Sí Lista de IDs de municipios (e.g., 41,20).
Ejemplo de petición

GET /api/v1/clima-pronostico/municipios?municipios=42,41

Ejemplo de respuesta exitosa (200 OK)
{
  "error": false,
  "status": 200,
  "message": "Clima por municipios obtenido correctamente.",
  "data": {
    "41": {
      "nombre_municipio": "Victoria",
      "nombre_estado": "Tamaulipas",
      "latitud": 23.7311,
      "longitud": -99.1513,
      "pronostico": [
        {
          "dia_local": "2025-06-24",
          "numero_dia": 0,
          "temperatura_maxima_c": 31.7,
          "temperatura_minima_c": 18.9,
          "descripcion_cielo": "Poco nuboso",
          "probabilidad_precipitacion_porcentaje": 50,
          "precipitacion_litros_m2": 14.7,
          "velocidad_viento_kmh": 10.6,
          "direccion_viento_cardinal": "Sureste",
          "direccion_viento_grados": "135.0",
          "cobertura_nubes_porcentaje": "7.75",
          "latitud": 23.7311,
          "longitud": -99.1513,
          "diferencia_utc": "6"
        }
      ]
    },
    "42": {
      "nombre_municipio": "Villagrán",
      "nombre_estado": "Tamaulipas",
      "latitud": 24.4732,
      "longitud": -99.4881,
      "pronostico": [
        {
          "dia_local": "2025-06-24",
          "numero_dia": 0,
          "temperatura_maxima_c": 34.3,
          "temperatura_minima_c": 19.9,
          "descripcion_cielo": "Despejado",
          "probabilidad_precipitacion_porcentaje": 90,
          "precipitacion_litros_m2": 6.4,
          "velocidad_viento_kmh": 14.2,
          "direccion_viento_cardinal": "Sureste",
          "direccion_viento_grados": "135.0",
          "cobertura_nubes_porcentaje": "5.61",
          "latitud": 24.4732,
          "longitud": -99.4881,
          "diferencia_utc": "6"
        }
      ]
    }
  },
  "metadata": {
    "Organization": "Agencia de Innovación e Inteligencia Digital de Tamaulipas",
    "Department": "Departamento de Desarrollo de Soluciones Informáticas"
  }
}

 

🧬 Tipos de datos

📌 ClimaActualResponse

Ambos endpoints (/api/v1/clima-actual y /api/v1/clima-pronostico) utilizan la misma estructura de datos para representar la información climática de un día determinado. La diferencia radica en la cantidad de registros: el primero devuelve un solo objeto (data), mientras que el segundo entrega un arreglo de objetos bajo data[], representando varios días consecutivos.

Campo Tipo Fuente (CONAGUA) Descripción
id_estado int ides ID del estado.
id_municipio int idmun ID del municipio.
nombre_estado string nes Nombre del estado.
nombre_municipio string nmun Nombre del municipio.
dia_local string dloc Fecha y hora local en formato YYYY-MM-DD HH:MM:SS.
numero_dia int ndia Número del día dentro del conjunto pronosticado (0 = hoy).
temperatura_maxima_c string tmax Temperatura máxima esperada en °C.
temperatura_minima_c string tmin Temperatura mínima esperada en °C.
descripcion_cielo string desciel Descripción del cielo (Ej. "Poco nuboso").
probabilidad_precipitacion_porcentaje int probprec Porcentaje de probabilidad de precipitación.
precipitacion_litros_m2 string prec Precipitación estimada en litros por metro cuadrado.
velocidad_viento_kmh string velvien Velocidad del viento en km/h.
direccion_viento_cardinal string dirvienc Dirección cardinal del viento (Ej. "N", "SE", "Oeste").
direccion_viento_grados string dirvieng Dirección del viento en grados (0–360).
cobertura_nubes_porcentaje string cc Porcentaje estimado de cobertura nubosa.
latitud string lat Latitud de la ubicación consultada.
longitud string lon Longitud de la ubicación consultada.
diferencia_utc int dh Diferencia horaria respecto a UTC (Ej. 6 para UTC-6).

🔗 Referencias y Fuentes de Datos

La información climática proviene directamente de la API oficial de CONAGUA. Para consultar la documentación oficial y obtener mayor información técnica sobre los datos y servicios disponibles, visite:

Servicio Web CONAGUA - SMN