API de Inteligencia de Fuentes Abiertas (OSINT)

La API de Inteligencia de Fuentes Abiertas (OSINT) de DataInt proporciona acceso en tiempo real a información sobre eventos disruptivos detectados a través de múltiples fuentes abiertas. Esta API es fundamental para operaciones de inteligencia, gestión de riesgos y toma de decisiones estratégicas.

Resumen de la API de Inteligencia de Fuentes Abiertas (OSINT)

El servicio OSINT de DataInt utiliza tecnologías avanzadas de procesamiento de lenguaje natural y análisis de datos paraDetectar eventos disruptivos como manifestaciones, bloqueos, incidentes de seguridad y desastres naturales en fuentes abiertas. Nuestro sistema monitorea continuamente redes sociales y una lista curada de más 300 portales de noticias locales y nacionales. Así mismo, este servicio permite a nuestros usuarios gestionar activos personalizados (en la forma de puntos de interés y geo-cercas) para monitorear eventos relevantes en ubicaciones específicas. Finalmente, el servicio OSINT también ofrece un sistema de alertas que notifica a los usuarios sobre eventos que cumplen criterios específicos, permitiendo una respuesta rápida y efectiva ante situaciones críticas.

Características Principales

Detección en Tiempo Real

Monitoreo continuo de fuentes abiertas para identificación inmediata de eventos disruptivos con verificación automática de fuentes.

Geolocalización Precisa

Todos los eventos incluyen coordenadas geográficas precisas con capacidades de búsqueda espacial y filtrado por áreas específicas.

Filtrado Avanzado

Sistema completo de filtros por ubicación, tipo de evento, severidad y fechas, para consultas específicas.

Estadística Descriptiva

Herramientas de análisis para identificar patrones temporales y tendencias geográficas.

Sistema de Alertas

Configuración de reglas personalizadas para notificaciones automáticas basadas en criterios específicos del usuario.

Múltiples Formatos

Exportación de datos en formatos CSV, GeoJSON y KML para integración con sistemas externos y herramientas de análisis.

Categorías de Endpoints

1. Eventos Disruptivos (/v1/event)

Endpoints principales para consultar eventos disruptivos detectados en tiempo real a través de inteligencia de fuentes abiertas.

• GET /v1/event - Consulta principal de eventos con filtros avanzados
• POST /v1/event/by-geometry - Búsqueda de eventos dentro de una geo-cerca específica
• PATCH /v1/event/report/{uuid} - Marcar un evento como no relevante o falso positivo

El filtrado de eventos admite los siguientes parámetros:

• start_date y end_date: Filtrar eventos por rango de fechas.
• state_id y municipality_id: Filtrar eventos por estado o municipio. Al igual que en el servicio de incidencia delictiva, estos IDs deben ser númericos, con una longitud de 2 y 5 dígitos, respectivamente, con llenado con ceros a la izquierda según sea necesario (por ejemplo, “09” para el estado de Guerrero o “09001” para el municipio de Acapulco de Juárez).
• event_type: Filtrar por tipo de evento.
• severity: Filtrar por nivel de severidad del evento.
• asset: El UUID del activo para filtrar eventos asociados a un punto de interés o geo-cerca específica. Si se proporciona el UUID de un activo representado como un punto de interés, es necesario proveer el parámetro radius para definir el radio de búsqueda alrededor del punto (en metros). Si se proporciona el UUID de un activo representado como una geo-cerca, no es necesario el parámetro radius, ya que la búsqueda se realizará dentro de los límites definidos por la geo-cerca.

Los tipos de eventos disponibles incluyen:

• Incidentes de tránsito e interrupciones viales (traffic);
• Eventos metereológicos, como tormentas, huracanes o tornados (weather);
• Eventos geológicos, como sismos o erupciones volcánicas (geological);
• Protestas y manifestaciones (protest);
• Disturbios y saqueos (social_unrest);
• Enfrentamientos armados (armed_confrontation);
• Delitos (crime).
• Fallas en infraestructura, como cortes masivos de luz, colapso de puentes o fallas en servicios públicos (infrastructure).
• Terrorismo (terrorism).

Los niveles de severidad disponibles son:

• Bajo: Eventos que no representan una amenaza inmediata o grave (low).
• Medio: Eventos que pueden causar interrupciones o riesgos moderados (medium).
• Alto: Eventos que representan una amenaza significativa a la seguridad pública (high).
• Crítico: Eventos que representan una amenaza inminente y grave (critical).

Adicionalmente, el endpoint de filtrado de eventos permite paginación para facilitar la gestión de grandes volúmenes de datos. Para ello, se pueden utilizar los parámetros skip y limit para controlar la paginación.

Tip

Recomendamos utilizar paginación en las consultas para optimizar el rendimiento y evitar tiempos de espera prolongados, especialmente cuando se trabaja con grandes conjuntos de datos.

De igual forma, recomendamos tomar en cuenta que al filtrar eventos usando áreas geográficas extensas, como estados, el número de eventos retornados puede ser muy alto, lo que podría afectar el rendimiento de la consulta. En estos casos, es preferible utilizar geo-cercas más específicas o puntos de interés con un radio definido para obtener resultados más manejables y relevantes.

Note

El sistema de detección de eventos disruptivos está diseñado para minimizar falsos positivos mediante un proceso de verificación automática que evalúa la credibilidad de las fuentes y la consistencia de la información. Sin embargo, dada la naturaleza dinámica y a veces caótica de las fuentes abiertas, es posible que algunos eventos reportados no sean relevantes o precisos. Por ello, ofrecemos a los usuarios la capacidad de marcar eventos como no relevantes o falsos positivos mediante el endpoint PATCH /v1/event/report/{uuid}. Esta funcionalidad permite a los usuarios contribuir a la mejora continua del sistema al proporcionar retroalimentación sobre la calidad de los datos.

2. Análisis Agregados de Eventos (/v1/analysis/event/dow-hours)

Herramientas de análisis estadístico para identificar patrones temporales y tendencias en eventos disruptivos.

• GET /v1/analysis/event/dow-hours - Análisis de patrones temporales por día de la semana y hora
• GET /v1/analysis/event/timeline - Línea de tiempo de eventos
• GET /v1/analysis/event/count-by-type-summary - Resumen por tipo de evento
• GET /v1/analysis/event/count-by-location - Conteo por ubicación geográfica

Estos endpoints admiten los mismos parámetros de filtrado que el endpoint principal de eventos disruptivos, permitiendo análisis personalizados según las necesidades del usuario.

3. Fuentes OSINT (/v1/news)

Acceso a noticias y artículos relacionados con eventos disruptivos de múltiples fuentes de inteligencia de fuente abierta.

• GET /v1/news - Noticias relacionadas con eventos disruptivos
• GET /v1/news/sources - Catálogo de fuentes OSINT detectadas en un momento dado
• GET /v1/news/by-cluster - Búsqueda de noticias agrupadas por clustering

4. Activos (/v1/asset)

Gestión de activos (puntos de interés y geo-cercas) para monitoreo personalizado de eventos disruptivos.

• GET /v1/asset - Listar activos registrados
• POST /v1/asset - Crear nuevo activo para seguimiento
• PUT /v1/asset/{uuid} - Actualizar configuración de activo existente
• DELETE /v1/asset/{uuid} - Eliminar activo del sistema

Actualmente, nuestro sistema soporta dos tipos de activos:

• Puntos de interés: Representados por un punto geográfico (latitud y longitud). Estos son útiles para monitorear eventos dentro de un radio específico alrededor de una ubicación, como una oficina, bodega o instalación crítica.
• Geo-cercas: Definidas por un polígono geográfico que delimita un área específica. Estas son útiles para monitorear eventos dentro de áreas más amplias, como zonas industriales, barrios o regiones enteras.

En el caso de ambos tipos de activos, al momento de crearlos o editarlos es necesario definir su información geográfica usando GeoJSON.

5. Notificaciones (/v1/notification/rules)

Sistema de alertas y reglas de notificación para eventos que cumplan criterios específicos.

• GET /v1/notification/rules - Obtener reglas de notificación configuradas
• POST /v1/notification/rules - Crear nueva regla de alerta personalizada
• PUT /v1/notification/rules - Actualizar regla de notificación existente
• DELETE /v1/notification/rules/{uuid} - Eliminar regla de notificación
• GET /v1/notification/usage - Estadísticas de uso del sistema de alertas

Las reglas de notificación permiten a los usuarios definir criterios específicos para recibir alertas automáticas sobre eventos que cumplan con sus parámetros personalizados. Esto incluye la capacidad de filtrar por tipo de evento, ubicación geográfica, severidad o tipo. Las notificaciones pueden ser enviadas a través de dos canales: correo electrónico y SMS.

Una regla de notificación está compuesta por los siguientes elementos:

• uuid: Identificador único de la regla de notificación (asignado automáticamente al crear la regla).
• channel: Array de canales de notificación configurados
  • channel_id: Tipo de canal (sms o email)
  • channel_address: Dirección de destino (número de teléfono para SMS o correo electrónico)
• municipality_id: Array de IDs de municipios para filtrar eventos (formato de 5 dígitos con ceros a la izquierda)
• severity: Array de niveles de severidad a monitorear (low, medium, high, critical)
• event_type: Array de tipos de eventos a incluir (traffic, weather, geological, protest, social_unrest, armed_confrontation, crime, infrastructure, terrorism)
• assets: Array de activos asociados para monitoreo geográfico
  • asset_uuid: Identificador único del activo (punto de interés o geo-cerca)
  • distance: Radio de búsqueda en metros (solo aplica para puntos de interés)

{
  "uuid": "string",
  "channel": [
    {
      "channel_id": "sms",
      "channel_address": "string"
    }
  ],
  "municipality_id": [
    "string"
  ],
  "severity": [
    "low"
  ],
  "event_type": [
    "traffic"
  ],
  "assets": [
    {
      "asset_uuid": "string",
      "distance": 0
    }
  ]
}

Cuando uno de los eventos detectados cumple con los criterios de una regla de notificación, el sistema envía alertas automáticas a los canales configurados. Esto permite a los usuarios recibir información crítica en tiempo real y tomar decisiones informadas rápidamente.

Los eventos que cumplen con los criterios de más de una regla de notificación se envían a todos los canales configurados en las mismas, lo que permite a los usuarios recibir alertas a través de múltiples medios según sus preferencias.

Caution

El sistema de notificaciones está diseñado para ser altamente configurable, permitiendo a los usuarios adaptar las alertas a sus necesidades operativas específicas. Sin embargo, recomendamos establecer criterios claros y específicos para evitar la sobrecarga de información, asegurar que las alertas sean relevantes y evitar costos innecesarios asociados al envío de mensajes SMS o correos electrónicos.

6. Exportación de Datos

Endpoints especializados para exportar datos en múltiples formatos para integración con sistemas externos.

• GET /v1/event.csv - Exportación en formato CSV para análisis en hojas de cálculo
• GET /v1/event.geojson - Exportación en formato GeoJSON para sistemas GIS
• GET /v1/event.kml - Exportación en formato KML para Google Earth
• POST /v1/event/by-geometry.csv - CSV de eventos usando una geo-cerca específica
• POST /v1/event/by-geometry.geojson - GeoJSON de eventos usando una geo-cerca específica
• POST /v1/event/by-geometry.kml - KML de eventos usando una geo-cerca específica

Autenticación y Permisos

La API OSINT requiere autenticación OAuth2 con los siguientes scopes específicos para cada categoría:

Eventos Disruptivos

• osint:event:read - Consulta de eventos disruptivos y reportes detallados

Análisis Agregados

• osint:event:read - Acceso a análisis estadísticos y patrones temporales

Fuentes OSINT

• osint:news:read - Acceso a noticias relacionadas y fuentes de inteligencia

Gestión de Activos

• osint:asset:read - Consulta de activos registrados
• osint:asset:create - Creación de nuevos activos para monitoreo
• osint:asset:update - Modificación de configuración de activos
• osint:asset:delete - Eliminación de activos del sistema

Sistema de Notificaciones

• osint:notification:read - Consulta de reglas de notificación configuradas
• osint:notification:write - Creación y modificación de reglas de alerta
• osint:notification:delete - Eliminación de reglas de notificación

Límites y Consideraciones

• Rate Limiting: Máximo 1000 requests por hora por API key
• Resultados por consulta: Recomendado máximo 100 eventos por request
• Retención de datos: Eventos disponibles por 90 días
• Cobertura geográfica: Enfoque principal en México con cobertura selectiva internacional

---

Especificación de la API