Documentación de la API de Calidad del Aire — MADES

Todas las solicitudes a los endpoints de datos requieren una clave API. Si aún no tiene una, puede registrarse aquí.

Incluya su clave API en las solicitudes HTTP usando uno de estos métodos:

Método	Header
Header personalizado	X-Api-Key: su_clave_api
Authorization Bearer	Authorization: Bearer su_clave_api

https://calidadaire.mades.gov.py/api/v1

GET /api/v1/stations

Listar todas las estaciones de monitoreo activas.

Ejemplo:

curl -H "X-Api-Key: su_clave_api" \
  https://calidadaire.mades.gov.py/api/v1/stations

Respuesta:

{
  "data": [
    {
      "id": 1,
      "name": "Estación Central",
      "type": "thermofisher",
      "station_code": "ASUN01",
      "city": "Asunción",
      "department": "Central",
      "latitude": -25.2637,
      "longitude": -57.5759,
      "is_active": true,
      "is_collecting_data": true,
      "is_under_maintenance": false
    }
  ]
}

---

GET /api/v1/stations/{'{id}'}

Obtener detalle de una estación específica.

Ejemplo:

curl -H "X-Api-Key: su_clave_api" \
  https://calidadaire.mades.gov.py/api/v1/stations/1

---

GET /api/v1/stations/{'{id}'}/data

Obtener datos de calidad del aire de una estación, con paginación por cursor.

Parámetro	Tipo	Descripción
parameter_name	string (opcional)	Filtrar por nombre de parámetro (ej: pm25, co, no2)
date_from	date (obligatorio)	Fecha de inicio (formato: YYYY-MM-DD). No puede ser posterior a hoy.
date_to	date (obligatorio)	Fecha de fin (formato: YYYY-MM-DD). No puede ser posterior a hoy. Rango máximo: 1 año.
per_page	integer (opcional)	Resultados por página (1-100, default: 100)

Ejemplo:

curl -H "X-Api-Key: su_clave_api" \
  "https://calidadaire.mades.gov.py/api/v1/stations/1/data?parameter_name=pm25&date_from=2025-09-01&date_to=2025-09-30&per_page=50"

Respuesta:

{
  "data": [
    {
      "date_time": "2025-09-30T23:00:00+00:00",
      "parameter_name": "pm25",
      "parameter_value": 12.5
    }
  ],
  "next_cursor": "eyJpZCI6MTAwfQ",
  "next_page_url": "https://calidadaire.mades.gov.py/api/v1/stations/1/data?cursor=eyJpZCI6MTAwfQ",
  "prev_cursor": null,
  "prev_page_url": null
}

---

GET /api/v1/parameters

Listar todos los parámetros medidos con las estaciones que los reportan y el rango de fechas disponible.

Ejemplo:

curl -H "X-Api-Key: su_clave_api" \
  https://calidadaire.mades.gov.py/api/v1/parameters

Respuesta:

{
  "data": [
    {
      "parameter_name": "pm25",
      "stations": [
        {
          "id": 1,
          "name": "Estación Central",
          "data_from": "2025-01-01 00:00:00",
          "data_to": "2025-09-30 23:00:00"
        }
      ]
    }
  ]
}

El endpoint de datos usa paginación por cursor, que es más eficiente para conjuntos de datos grandes. La respuesta incluye next_page_url y prev_page_url para navegar entre páginas.

Para obtener la siguiente página, use la URL proporcionada en next_page_url:

curl -H "X-Api-Key: su_clave_api" \
  "https://calidadaire.mades.gov.py/api/v1/stations/1/data?cursor=eyJpZCI6MTAwfQ"

Cuando next_page_url es null, no hay más páginas disponibles.

Código	Descripción
200	Solicitud exitosa
401	Clave API no proporcionada o inválida
403	Correo no verificado o acceso revocado
404	Recurso no encontrado
422	Error de validación en los parámetros de consulta
429	Límite de solicitudes excedido

• 60 solicitudes por minuto por clave API
• 3 registros por minuto por dirección IP

Si excede el límite, recibirá una respuesta 429 Too Many Requests. Espere un momento antes de reintentar.