Referencia de la API v1 · solo lectura

1 · Resumen

Esta API expone, de forma programática y de solo lectura, el conjunto de datos que alimenta el mapa de crisisvenezuela.org tras el terremoto del 24 de junio de 2026. Cada registro es un hecho corroborado de una de tres categorías:

• daño — un reporte de daño o colapso estructural (un edificio, una estructura).
• acopio — un punto o centro de recolección de ayuda.
• necesidad — una solicitud de un recurso (agua, medicinas, rescate…).

¿Para quién? Periodistas, ONG, desarrolladores de mapas/dashboards, y —especialmente— los equipos de los propios sitios que originan los datos, que pueden consumir la API sin reingestar su propia información gracias a la procedencia por registro (ver excluir_fuente).

URL base:

Sin autenticación · CORS abierto (Access-Control-Allow-Origin: *) · respuestas cacheadas en CDN · especificación legible por máquina en /api/v1/openapi.json (OpenAPI 3.1). Licencia de los datos: CC-BY-4.0.

Los nombres de parámetros y de campos están en español; se mantienen en inglés solo los términos técnicos universales: bbox, offset y los valores de formato (json | geojson | csv).

2 · Inicio rápido

Una sola petición que devuelve datos de inmediato (los 1000 hechos más recientes, JSON):

curl https://crisisvenezuela.org/api/v1/facts

La respuesta es un sobre con metadatos y un arreglo datos:

{
  "meta": {
    "cantidad": 1000,
    "total": 1342,
    "generado": "2026-06-27T18:00:00.000Z",
    "licencia": "CC-BY-4.0",
    "atribucion": "crisisvenezuela.org + fuentes originales",
    "consulta": { "limite": 1000, "offset": 0, "formato": "json" }
  },
  "datos": [
    {
      "id": "chacao-2879654398988377755",
      "categoria": "daño",
      "nivel": "colapso_total",
      "estructura": "Edificio San Judas Tadeo",
      "municipio": "Chacao",
      "estado": "Miranda",
      "zona": "El Rosal",
      "lat": 10.497, "lon": -66.853,
      "coord_origen": "explicita",
      "descripcion": "Colapso total del edificio, hay personas atrapadas bajo los escombros.",
      "tipo_necesidad": null,
      "atrapados": true,
      "n_fuentes": 3,
      "fuentes": [
        { "fuente": "terremotovenezuela.com", "url": "https://terremotovenezuela.com/edificio/..." },
        { "fuente": "elnacional.com", "url": "https://www.elnacional.com/..." }
      ],
      "fecha": "2026-06-26T14:02:00Z",
      "primera_vez": "2026-06-24T22:10:00Z"
    }
  ]
}

3 · Modelo de datos

Cada elemento de datos (y cada properties en GeoJSON, y cada fila en CSV) es un hecho con estos campos:

4 · Cómo se construyen los datos

Transparencia sobre la naturaleza y los límites del dato. El pipeline tiene cuatro etapas:

1. Agregación de fuentes públicas. Leemos prensa, redes sociales y plataformas ciudadanas (p. ej. terremotovenezuela.com, acopiove, RedQuipu y reportes ciudadanos). Cada ítem conserva su URL de origen.
2. Triaje y normalización por IA. Un modelo de lenguaje decide si el reporte es relevante, lo clasifica (daño / acopio / necesidad), extrae municipio, estado, zona, estructura y tipo de necesidad, y resume el hecho en una frase en español. Lo irrelevante o en otro idioma se descarta.
3. Geolocalización. Si el reporte trae coordenadas (o la fuente las publica en su catálogo) se usan directamente (coord_origen=explicita). Si no, la IA extrae un nombre de lugar y un geocodificador OSM / Nominatim lo resuelve a un punto (coord_origen=geocodificada, aproximado).
4. Corroboración y deduplicación. El mismo hecho contado por varias fuentes se fusiona en un solo registro con SimHash (huella del texto): «4 edificios colapsaron en Chacao» dicho de cinco maneras cuenta una vez, con n_fuentes=5. Se conserva la fuente más creíble como primaria y todas las fuentes en fuentes[].

5 · Fuentes (de dónde vienen los datos)

El conjunto agrega fuentes públicas de tres tipos —redes sociales y fediverso, prensa, y catálogos estructurados del ecosistema— y las corrobora entre sí. Esta es la vista general: cada registro lleva su lista exacta de orígenes en el campo fuentes, así que el detalle hecho por hecho vive en cada registro, no aquí.

Puedes filtrar por origen con fuente y excluir_fuente, y exigir corroboración —varias fuentes para un mismo hecho— con min_fuentes. Los conteos de abajo son aproximados (se mueven en vivo) y se solapan: un hecho reportado por una red social y por la prensa cuenta en ambas filas —eso es justamente la corroboración—, así que no suman el total de ~10.800 hechos.

6 · Procedencia de coordenadas (coord_origen)

No todas las coordenadas son iguales. El campo coord_origen te dice de dónde salieron lat/lon, para que sepas cuánto confiar en su precisión y puedas filtrar:

explicita

Las coordenadas vinieron con el dato: del catálogo de la fuente original (p. ej. terremotovenezuela.com o acopiove) o indicadas explícitamente en el post. Alta precisión — apuntan al lugar real del hecho.

geocodificada

No venían con el dato: el pipeline las derivó. La IA extrajo un nombre de lugar (barrio, urbanización, municipio) y un geocodificador OSM / Nominatim lo resolvió a un punto. Son aproximadas: pueden caer en el centroide del área o estar desplazadas algunos cientos de metros. Corregimos manualmente los errores conocidos cuando los detectamos.

"" (vacío)

Sin procedencia conocida o sin coordenadas (lat/lon en null).

# Solo hechos con coordenadas precisas, en GeoJSON listo para un mapa
curl "https://crisisvenezuela.org/api/v1/facts?coord_origen=explicita&formato=geojson"

7 · Filtros

Todos los parámetros son opcionales y combinables (se aplican en conjunto, tipo AND). Las listas van separadas por comas. Un valor inválido en categoria, bbox, desde, formato o en los enteros devuelve 400 con {"error": "…"}; los parámetros desconocidos se ignoran. Recuerda codificar la URL (espacios → %20, ñ → %C3%B1).

anti-circular excluir_fuente en detalle

Si mantienes uno de los sitios fuente, excluye tus propios datos para no reingestar lo tuyo y evitar bucles de retroalimentación. La regla es deliberada: un hecho solo se descarta si todas sus fuentes están en la lista de exclusión; si además lo confirma una fuente independiente, el hecho permanece (no pierdes corroboración externa).

# "Soy terremotovenezuela.com: dame todo MENOS lo que solo provengo yo"
curl "https://crisisvenezuela.org/api/v1/facts?excluir_fuente=terremotovenezuela.com"

Más ejemplos

filtros Acopios en el Distrito Capital, máximo 50:

curl "https://crisisvenezuela.org/api/v1/facts?categoria=acopio&estado=Distrito%20Capital&limite=50"

necesidades Solicitudes de agua o medicinas, muy corroboradas (≥2 fuentes), desde una fecha:

curl "https://crisisvenezuela.org/api/v1/facts?categoria=necesidad&tipo_necesidad=agua,medicinas&min_fuentes=2&desde=2026-06-25T00:00:00Z"

8 · Formatos de salida

Elige con formato:

json (por defecto)

Sobre { "meta": {…}, "datos": [ Hecho, … ] }. meta incluye cantidad (en esta página), total (tras filtros, antes de paginar), generado, licencia, atribucion y consulta (eco de los parámetros aplicados). Content-Type: application/json.

geojson

FeatureCollection (RFC 7946) con solo los registros geolocalizados. Cada feature tiene geometry.coordinates = [lon, lat] y el hecho completo (sin lat/lon) en properties. meta va como miembro extranjero informativo. Content-Type: application/geo+json. Ideal para Leaflet, Mapbox, QGIS, etc.

csv

Tabla con cabecera; una fila por hecho. Las fuentes se aplanan a una columna fuentes con el formato nombre(url);nombre(url). Incluye BOM UTF-8 para abrir limpio en Excel. Content-Type: text/csv.

# GeoJSON de una zona, listo para pintar en un mapa
curl "https://crisisvenezuela.org/api/v1/facts?formato=geojson&bbox=-67.5,10.0,-66.5,10.7"

# CSV de daños desde una fecha (da%C3%B1o = "daño" codificado para URL)
curl "https://crisisvenezuela.org/api/v1/facts?categoria=da%C3%B1o&desde=2026-06-25T00:00:00Z&formato=csv"

9 · Procedencia y atribución

Cada hecho conserva en fuentes[] todas sus fuentes distintas (nombre + URL). Esto cumple dos funciones:

• Deduplicar contra tus datos. Antes de ingerir un hecho, revisa sus fuentes / url: si ya lo tienes (o es tuyo), omítelo. Combínalo con excluir_fuente para filtrarlo del lado del servidor.
• Dar crédito. Al reutilizar, cita la fuente original cuando corresponda, además de crisisvenezuela.org.

10 · Límites y uso justo

• Caché. Cada respuesta trae Cache-Control: public, max-age=60, s-maxage=120; el CDN absorbe consultas repetidas. Los datos se refrescan en vivo, con un retraso de hasta ~1–2 min.
• Paginación. limite tope 5000 por petición; usa offset para recorrer, o desde para traer solo lo nuevo.
• Descargas masivas → usa los volcados estáticos. No martilles el endpoint de consulta. Para el conjunto completo o cargas frecuentes, sirve el CDN directamente:
  • /facts.json — el conjunto completo (los mismos registros que esta API).
  • /colapsos.json · /colapsos.csv — solo estructuras colapsadas/dañadas con nombre.
• Solo lectura. La API únicamente sirve GET (y OPTIONS para CORS). Otros métodos devuelven 405.

11 · Versionado

La ruta lleva la versión mayor: /api/v1/…. Política de estabilidad de v1:

• Cambios aditivos no rompen. Podemos agregar campos nuevos a los registros o nuevos parámetros opcionales sin cambiar de versión; tu cliente debe ignorar lo que no conozca.
• Cambios incompatibles → nueva versión. Renombrar/eliminar campos o cambiar el significado de uno existente se publicaría como /api/v2; v1 seguiría disponible durante una transición.
• Contrato legible por máquina: /api/v1/openapi.json (OpenAPI 3.1) — genera clientes o valida contra él.