Referencia de la API v1 · solo lectura

1 · Resumen

Esta API expone, de forma programática y de solo lectura, el conjunto de datos de crisisvenezuela.org. Hay siete categorías; solo las tres primeras se renderizan como marcadores:

• 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…).
• información — contexto general relevante, nunca daño rojo.
• evaluación_pendiente — evaluación SismoAyuda aún no completada.
• evaluación_habitable — la fuente reporta ocupación sin restricciones; puede coexistir con daño leve o moderado y no es una verificación independiente.
• evaluación_inconsistente — campos fuente contradictorios, en revisión.

Fuera de alcance: conteos de fallecidos/heridos, listas de víctimas y búsquedas de personas desaparecidas. Se conservan únicamente referencias a personas afectadas cuando forman parte de un punto accionable de ayuda, necesidad o 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": "cv-219c7ab54981438cbe05e2fb",
      "categoria": "daño",
      "nivel": "colapso_total",
      "conflicto_nivel": false,
      "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/...", "post_id": "terremotove:...", "observado_en": "2026-06-26T14:02:00Z", "entity_support": "source_record", "media_entity_support": "source_record" },
        { "fuente": "elnacional.com", "url": "https://www.elnacional.com/...", "post_id": "rss:...", "observado_en": "2026-06-26T13:58:00Z", "entity_support": "explicit_name", "media_entity_support": "single_entity" }
      ],
      "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 fail-closed. Cada registro requiere un veredicto exitoso. Un fallo o respuesta parcial bloquea la publicación; información general y evaluaciones neutrales conservan categorías separadas.
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. Entidad y procedencia. Solo se fusionan estructuras nombradas de forma compatible. Fechas y fotos provienen exclusivamente de las fuentes que respaldan esa entidad; medios multi-entidad ambiguos se omiten.

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 agrupa reportes que parecen describir el mismo hecho. Esta es la vista general: cada registro lleva su procedencia exacta en fuentes. Agrupar nombres o publicaciones no presume que sus orígenes sean independientes.

Puedes filtrar por fuente con fuente y excluir_fuente, y exigir varios registros de fuente con min_fuentes. Ese filtro mide volumen de apoyo, no independencia confirmada. Los conteos de abajo son aproximados, cambian con cada exportación, se solapan y no suman el total.

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. Su precisión no está verificada de forma independiente; una fuente puede publicar un punto aproximado o de relleno.

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 suministradas por la fuente, en GeoJSON
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 otra fuente no excluida también lo reporta, el hecho permanece y conserva esa procedencia 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 respaldadas por ≥2 registros de fuente, 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. Las exportaciones se regeneran periódicamente y cada respuesta indica su hora de generación.
• 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.