API pública de Vigía

Referencia para integrar los datos de riesgo, alertas y sismos de Vigía en otras aplicaciones, sin reproducir la lógica de la plataforma.

Introducción

La API de Vigía entrega en JSON los datos que produce la plataforma, para que otras aplicaciones los usen sin reproducir la lógica de cálculo. Es de solo lectura, no requiere clave ni registro y admite llamadas desde cualquier origen (CORS abierto).

URL base: https://vigia.redlabot.org/api/v1
Especificación OpenAPI 3: /api/v1/openapi.json. Impórtela en Postman, Insomnia o Swagger UI, o genere un cliente tipado con las herramientas de OpenAPI.

Recursos disponibles de la API v1
Recurso	Qué devuelve
`/api/v1/veredas`	Listado de veredas con su caja envolvente y centro.
`/api/v1/veredas/{codigoVereda}`	Riesgo compuesto de una vereda.
`/api/v1/riesgo`	Riesgo compuesto de todas las veredas, en JSON o GeoJSON.
`/api/v1/alertas`	Alertas emitidas en las últimas 72 horas.
`/api/v1/sismos`	Sismos recientes de SGC y USGS, sin duplicados.

Vigía no es un sistema oficial de alerta. Los datos son una ayuda para la toma de decisiones. Ante una emergencia, llame al 123.

Convenciones

Sobre de respuesta

Toda respuesta correcta tiene la forma { data, meta }. El contenido está en data. En meta viaja generadoEn (fecha ISO 8601 en UTC), la atribucion que debe citar y, en los listados, total. Los ejemplos de esta página abrevian la atribución con puntos suspensivos.

Formato de los datos

Los nombres de los campos van en español y en camelCase.
Las coordenadas son latitud y longitud en grados (WGS84). Una caja envolvente se expresa como sur, oeste, norte, este.
Un valor null significa que el dato no está disponible, no que sea cero.

Errores

Los errores devuelven el código HTTP correspondiente y un cuerpo con esta forma:

Respuesta 400

{
  "error": {
    "code": "invalid_parameter",
    "message": "El parámetro accion debe ser informar, prepararse o actuar."
  }
}

Códigos de estado de la API
HTTP	error.code	Significado
200	-	Respuesta correcta.
400	`invalid_parameter`	Un parámetro tiene un valor que no se acepta.
404	`not_found`	El recurso pedido no existe, por ejemplo un código de vereda desconocido.
502	`upstream_error`	Falló una de las fuentes de datos. Reintente más tarde.

Caché y frescura

Las respuestas se guardan en caché en el borde de la red, así que un dato puede tener hasta este tiempo de antigüedad. Revise meta.generadoEn si necesita saber cuándo se calculó.

Frescura máxima por recurso
Recurso	Antigüedad máxima
Veredas	24 horas
Riesgo (una vereda o todas)	10 minutos
Alertas	1 minuto
Sismos	2 minutos

Veredas

Catálogo de las veredas y cascos urbanos que cubre Vigía. Sirve para obtener los códigos que luego se usan en el resto de la API.

Listado de veredas

GET/api/v1/veredas

Devuelve cada vereda con su caja envolvente (bbox) y su centro. Los cascos urbanos se marcan con esCascoUrbano.

Parámetros de /api/v1/veredas
Parámetro	Dónde	Tipo	Descripción
`municipio`	query	texto	Filtra por municipio. No distingue mayúsculas ni tildes.

Petición

curl "https://vigia.redlabot.org/api/v1/veredas?municipio=Zarzal"

Respuesta (recortada a un elemento de 19)

{
  "data": [
    {
      "codigoVereda": "76895-urbano",
      "nombre": "Casco Urbano",
      "municipio": "Zarzal",
      "esCascoUrbano": true,
      "bbox": { "sur": 4.3712, "oeste": -76.0819, "norte": 4.4081, "este": -76.0592 },
      "centro": { "lat": 4.3897, "lon": -76.0705 }
    }
  ],
  "meta": {
    "generadoEn": "2026-10-24T18:27:49.010Z",
    "atribucion": "Vigía (RED LabOT). Datos derivados de IDEAM, SGC, USGS…",
    "total": 19
  }
}

Frescura de los datos:: hasta 24 horas de antigüedad.
Errores específicos:: 502 upstream_error: no se pudo consultar el listado.

Riesgo compuesto de una vereda

GET/api/v1/veredas/{codigoVereda}

Devuelve el riesgo compuesto de una sola vereda, con el detalle por amenaza, población e infraestructura. El código sale del listado anterior.

Parámetros de /api/v1/veredas/{codigoVereda}
Parámetro	Dónde	Tipo	Descripción
`codigoVereda`obligatorio	ruta	texto	Código de la vereda, por ejemplo 76895011 o 76895-urbano.
`geometria`	query	booleano	Con true, añade el polígono de la vereda en data.geometria (GeoJSON). Por defecto: `false`.

Petición

curl "https://vigia.redlabot.org/api/v1/veredas/76895011"

Respuesta (amenazas recortadas a dos de cinco)

{
  "data": {
    "codigoVereda": "76895011",
    "nombre": "Sin Definir",
    "municipio": "Zarzal",
    "esCascoUrbano": false,
    "nivel": "Muy alto",
    "puntaje": 0.4656,
    "accion": "Actuar",
    "amenazaDominante": "sismologia",
    "amenazas": [
      {
        "amenaza": "inundaciones",
        "etiqueta": "Inundaciones",
        "nivel": "Muy alta",
        "puntaje": 0.8937,
        "detalle": "Quebrada más cercana: 0.12 km"
      },
      {
        "amenaza": "sismologia",
        "etiqueta": "Sismología",
        "nivel": "Muy alto",
        "puntaje": 0.941,
        "detalle": "Evento más cercano: 7.6 km (M 2.2)"
      }
    ],
    "poblacion": { "total": null, "menores5": null, "mayores60": null },
    "infraestructura": {
      "escuelas": null,
      "hospitales": null,
      "farmacias": null,
      "criticas": null,
      "sitiosCriticos": 0
    },
    "resumen": "Sin Definir (Zarzal) tiene un riesgo compuesto muy alto…"
  },
  "meta": { "generadoEn": "2026-10-24T18:27:59.115Z", "atribucion": "Vigía (RED LabOT). Datos derivados de IDEAM, SGC, USGS…" }
}

Frescura de los datos:: hasta 10 minutos de antigüedad.
Errores específicos:: 404 not_found: no existe una vereda con ese código.
502 upstream_error: no se pudo calcular el riesgo.

Riesgo compuesto

El riesgo de todas las veredas en una sola llamada, pensado para tableros, mapas y análisis en lote.

Riesgo de todas las veredas

GET/api/v1/riesgo

Cada elemento tiene la misma forma que el riesgo de una vereda. Con formato=geojson, data es una FeatureCollection y cada Feature lleva esos campos en properties y el polígono en geometry.

Parámetros de /api/v1/riesgo
Parámetro	Dónde	Tipo	Descripción
`municipio`	query	texto	Filtra por municipio. No distingue mayúsculas ni tildes.
`accion`	query	informar \| prepararse \| actuar	Devuelve las veredas con esa acción o una más grave. Con prepararse se obtienen las veredas en Prepararse y en Actuar.
`formato`	query	json \| geojson	Forma de data: lista de objetos o FeatureCollection. Por defecto: `json`.

Petición

curl "https://vigia.redlabot.org/api/v1/riesgo?municipio=Zarzal&accion=prepararse&formato=geojson"

Respuesta con formato=geojson (recortada)

{
  "data": {
    "type": "FeatureCollection",
    "features": [
      {
        "type": "Feature",
        "id": "76895011",
        "properties": {
          "codigoVereda": "76895011",
          "nombre": "Sin Definir",
          "municipio": "Zarzal",
          "nivel": "Muy alto",
          "puntaje": 0.4656,
          "accion": "Actuar",
          "amenazaDominante": "sismologia"
        },
        "geometry": { "type": "MultiPolygon", "coordinates": [ … ] }
      }
    ]
  },
  "meta": {
    "generadoEn": "2026-10-24T18:27:59.115Z",
    "atribucion": "Vigía (RED LabOT). Datos derivados de IDEAM, SGC, USGS…",
    "total": 19
  }
}

Frescura de los datos:: hasta 10 minutos de antigüedad.
Errores específicos:: 400 invalid_parameter: accion no es informar, prepararse ni actuar, o formato no es json ni geojson.
502 upstream_error: no se pudo calcular el riesgo compuesto.

Alertas

Las alertas que Vigía emitió en las últimas 72 horas. Son las mismas que reciben los suscriptores, pero la API nunca expone datos de ellos.

Alertas emitidas en las últimas 72 horas

GET/api/v1/alertas

Una lista vacía es lo normal cuando no hay nada que avisar. Solo existen dos niveles de alerta: prepararse y actuar.

Parámetros de /api/v1/alertas
Parámetro	Dónde	Tipo	Descripción
`amenaza`	query	deslizamientos \| inundaciones \| incendios \| sismos	Filtra por tipo de amenaza.

Petición

curl "https://vigia.redlabot.org/api/v1/alertas?amenaza=sismos"

Respuesta (ejemplo ilustrativo: al escribir esto no había alertas activas)

{
  "data": [
    {
      "id": "5b0f3c1e-8a27-4d6e-9c41-2f7a6d9e0b13",
      "amenaza": "sismos",
      "nivel": "prepararse",
      "zona": "Zarzal",
      "fecha": "2026-10-24T17:49:00.000Z",
      "magnitud": 4.8
    }
  ],
  "meta": {
    "generadoEn": "2026-10-24T18:27:49.774Z",
    "atribucion": "Vigía (RED LabOT). Datos derivados de IDEAM, SGC, USGS…",
    "total": 1,
    "ventanaHoras": 72
  }
}

Frescura de los datos:: hasta 1 minuto de antigüedad.
Errores específicos:: 400 invalid_parameter: amenaza no es una de las cuatro permitidas.
502 upstream_error: no se pudo leer el historial de alertas.

Sismos

Sismos recientes en el área de Vigía. Une el catálogo del Servicio Geológico Colombiano (SGC) y el de USGS, y cuando ambos reportan el mismo evento conserva el de SGC.

Sismos recientes

GET/api/v1/sismos

Ordenados del más reciente al más antiguo. meta.areaConsultada indica la caja geográfica que se consulta.

Parámetros de /api/v1/sismos
Parámetro	Dónde	Tipo	Descripción
`minMagnitud`	query	número, 0 a 10	Magnitud mínima. Por defecto: `0`.
`dias`	query	entero, 1 a 30	Cuántos días hacia atrás. Por defecto: `7`.
`limite`	query	entero, 1 a 200	Máximo de sismos devueltos. Por defecto: `50`.

Petición

curl "https://vigia.redlabot.org/api/v1/sismos?minMagnitud=3&dias=14&limite=10"

Respuesta

{
  "data": [
    {
      "id": "sgc-live-SGC2026uysjui",
      "fuente": "SGC",
      "fecha": "2026-10-24T17:49:00.000Z",
      "magnitud": 2.5,
      "profundidadKm": 8,
      "lat": 3.826,
      "lon": -75.6508,
      "lugar": "Chaparral - Tolima, Colombia",
      "revision": "manual"
    }
  ],
  "meta": {
    "generadoEn": "2026-10-24T18:27:49.010Z",
    "atribucion": "Vigía (RED LabOT). Datos derivados de IDEAM, SGC, USGS…",
    "total": 1,
    "areaConsultada": { "sur": 3.4, "oeste": -76.6, "norte": 5.2, "este": -75.2 }
  }
}

Frescura de los datos:: hasta 2 minutos de antigüedad.
Errores específicos:: 400 invalid_parameter: minMagnitud, dias o limite fuera de rango o no numéricos.
502 upstream_error: no se pudo consultar el catálogo sísmico.

Cómo interpretar el riesgo

Estos puntos evitan los errores de lectura más comunes. La metodología completa está en la documentación general.

nivel y puntaje no son lo mismo

nivel (Muy bajo, Bajo, Moderado, Alto, Muy alto) lo fija la amenaza más grave, siguiendo el criterio de la OMM y GDACS, no el promedio. Así una sola amenaza severa no se diluye entre las demás. puntaje es un promedio ponderado de 0 a 1 que sirve para ordenar veredas dentro de un mismo nivel, y no determina el nivel. Por eso una vereda en nivel Muy alto puede tener un puntaje bajo, como el 0.47 del ejemplo.

accion es lo que se recomienda hacer

Es Informar, Prepararse o Actuar, de menor a mayor gravedad. El filtro accion de /api/v1/riesgo usa ese orden: pedir prepararse incluye también las veredas en Actuar.

Cada amenaza tiene su propia escala

En amenazas viene una entrada por cada una: deslizamientos, inundaciones, incendios, precipitación y sismología. Sus etiquetas de nivel pueden variar entre amenazas (por ejemplo Baja o Bajo, Muy alta o Muy alto). Compare niveles solo dentro de la misma amenaza, o use el nivel global de la vereda. amenazaDominante indica cuál domina el resultado.

Cuándo aparece null

nivel, puntaje y accion son null cuando no hay datos suficientes para calcularlos. poblacion e infraestructura pueden ser null en veredas sin cifras disponibles; sitiosCriticos siempre es un entero.

Alertas

Solo hay dos niveles: prepararse y actuar. Se publican únicamente las alertas emitidas en vivo; los eventos que se registran en modo sombra, sin envío a suscriptores, no aparecen en la API.

Ejemplos de integración

Ejemplos mínimos para empezar. Compruebe siempre res.ok antes de usar data, porque un error devuelve error en lugar de data.

JavaScript

Veredas que requieren actuar

const BASE = "https://vigia.redlabot.org/api/v1"

async function veredasEnActuar(municipio) {
  const url = BASE + "/riesgo?accion=actuar&municipio=" + encodeURIComponent(municipio)
  const res = await fetch(url)
  const body = await res.json()
  if (!res.ok) throw new Error(body.error.code + ": " + body.error.message)
  return body.data
}

const veredas = await veredasEnActuar("Zarzal")
console.log(veredas.map((v) => v.nombre + ": " + v.nivel))

Python

Sismos de las últimas dos semanas

import requests

BASE = "https://vigia.redlabot.org/api/v1"

r = requests.get(BASE + "/sismos", params={"minMagnitud": 3, "dias": 14}, timeout=30)
r.raise_for_status()

for sismo in r.json()["data"]:
    print(sismo["fecha"], sismo["magnitud"], sismo["lugar"])

Mapa con MapLibre GL

Con formato=geojson, data se pasa directamente como fuente GeoJSON. Leaflet funciona igual.

Veredas coloreadas por acción

const res = await fetch("https://vigia.redlabot.org/api/v1/riesgo?formato=geojson")
const { data } = await res.json()

map.addSource("riesgo", { type: "geojson", data })
map.addLayer({
  id: "riesgo-relleno",
  type: "fill",
  source: "riesgo",
  paint: {
    "fill-opacity": 0.6,
    "fill-color": [
      "match", ["get", "accion"],
      "Actuar", "#d73027",
      "Prepararse", "#fdae61",
      "#91cf60"
    ]
  }
})

Descarga para QGIS u otro SIG

El sobre { data, meta } envuelve la colección, así que extraiga data antes de abrir el archivo en un SIG.

Terminal

curl -s "https://vigia.redlabot.org/api/v1/riesgo?formato=geojson" | jq .data > riesgo.geojson

Uso responsable

Respete el caché. No hay clave ni cuota por usuario, pero consultar con más frecuencia que la frescura indicada no devuelve datos nuevos y solo consume recursos. Pedir riesgo cada pocos minutos es suficiente.
Cite la fuente. Muestre la meta.atribucion de la respuesta, o al menos "Vigía (RED LabOT)", junto a los datos que publique.
No lo presente como alerta oficial. Vigía es una herramienta de apoyo. Las órdenes de evacuación y las alertas oficiales las emiten las autoridades.
Tolere campos nuevos. Se pueden añadir campos a la versión v1 sin aviso, así que su cliente debe ignorar los que no conozca. Los cambios que rompan la compatibilidad saldrán bajo una versión nueva de la ruta.
Cuéntenos qué construye. Si integra Vigía en una aplicación o necesita otro dato, escriba a apino@redlabot.org.