Consultar los eventos y logs de un viaje

[ POST ]

Devuelve los registros de geolocalización (ruta recorrida) y los eventos riesgosos detectados por la app de Airbag durante un viaje específico. Cada evento incluye su magnitud, la cual varía según el tipo y permite estimar la gravedad del comportamiento.

https://sync.airbagtech.io/trips/logs/{{TRIP_ID}}

Campos

Nombre	Tipo	Requerido	Descripción
TRIP_ID	String	Sí	ID del viaje a consultar. Debe enviarse en la ruta de la URL.
driverId	String	Sí	ID del conductor que ejecutó el viaje especificado en TRIP_ID. Acepta el ID que tu empresa usó al crear el conductor o el airbagId. Si el viaje no es de ese conductor, devuelve error.
showEvents	Boolean	No	Determina si se devuelven los eventos riesgosos. Valor por defecto: true.
showLogs	Boolean	No	Determina si se devuelven los logs de geolocalización. Valor por defecto: true.

Eventos riesgosos

Estos son los tipos de evento que puede devolver el endpoint en el arreglo data.events. Cada evento tiene su propia magnitud (value) cuya unidad depende del tipo.

5 tipos de evento

Velocidad

Comportamientos relacionados con la velocidad del vehículo.

• Exceso de velocidadspeeding

  La velocidad del conductor superó el límite permitido en esa vía. Si `speedLimit` es 999, significa que no se pudo obtener el límite legal para ese tramo.

Distracción

Eventos derivados de falta de atención al volante.

• Uso del celularphoneDistraction

  El conductor manipuló el celular mientras conducía a una velocidad superior a 15 km/h.

Maniobras agresivas

Fuerzas detectadas por el acelerómetro durante maniobras bruscas.

• Aceleraciónacceleration

  El conductor aceleró de manera agresiva.

• Frenadodeacceleration

  El conductor frenó de manera agresiva.

• Curva agresivacornering

  El conductor tomó una curva con excesiva fuerza lateral.

Equivalencias con los eventos de /provider-data

Los nombres de este endpoint no son los mismos que usa la sección de Eventos. Si combinas ambas fuentes, usa esta tabla:

Este endpoint (type)	/provider-data (event)
acceleration	acceleration
deacceleration	braking
cornering	cornering
speeding	speeding
phoneDistraction	phone_distraction

Headers

Content-Type	Authorization
application/json	apikey {{API_KEY}}

Body

{
  "driverId": "string",
  "showEvents": "boolean",
  "showLogs": "boolean"
}

Ejemplo

curl --location -g 'https://sync.airbagtech.io/trips/logs/{{TRIP_ID}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: apikey {{API_KEY}}' \
--data '{
  "driverId": "ID-1",
  "showEvents": true,
  "showLogs": false
}'

Respuestas

✅ Respuesta exitosa (200 OK)

Devuelve un objeto data con dos arreglos: events (eventos riesgosos detectados) y locationLogs (registros de geolocalización tomados a lo largo del viaje).

{
  "status": true,
  "data": {
    "events": [
      {
        "created": "2025-02-02T20:15:14.000Z",
        "country": "",
        "state": "",
        "lat": 19.42521,
        "lon": -99.18327,
        "type": "speeding",
        "value": 0,
        "legalSpeedLimit": 30,
        "speedLimit": 30,
        "speedViolation": 4.27,
        "hasCustomSpeedLimit": false
      },
      {
        "created": "2025-02-02T20:17:42.000Z",
        "country": "",
        "state": "",
        "lat": 19.42648,
        "lon": -99.18091,
        "type": "deacceleration",
        "value": 0.42
      },
      {
        "created": "2025-02-02T20:19:58.000Z",
        "country": "",
        "state": "",
        "lat": 19.42731,
        "lon": -99.17842,
        "type": "phoneDistraction",
        "value": 12.4
      }
    ],
    "locationLogs": [
      {
        "distracted": false,
        "created": "2025-02-02T20:11:45.000Z",
        "speed": 0,
        "speedLimit": 999,
        "speedViolation": 0,
        "lat": 19.42480,
        "lon": -99.18512
      },
      {
        "distracted": false,
        "created": "2025-02-02T20:15:14.000Z",
        "speed": 34.27,
        "speedLimit": 30,
        "speedViolation": 4.27,
        "lat": 19.42521,
        "lon": -99.18327
      },
      {
        "distracted": true,
        "created": "2025-02-02T20:19:58.000Z",
        "speed": 24.8,
        "speedLimit": 50,
        "speedViolation": 0,
        "lat": 19.42731,
        "lon": -99.17842
      }
    ]
  }
}

nota

En una respuesta real, locationLogs puede contener cientos o miles de registros (se toma una muestra cada ~1–6 segundos mientras el vehículo está en movimiento). El ejemplo se ha recortado por legibilidad.

Descripción de campos de respuesta

Campo	Tipo	Descripción
status	Boolean	Indica si la operación fue exitosa.
data	Object	Contenedor con los eventos y registros del viaje.
data.events	Array<Object>	Eventos riesgosos detectados durante el viaje. Viene vacío si showEvents es false. Ver tabla abajo.
data.locationLogs	Array<Object>	Registros de geolocalización ordenados cronológicamente. Viene vacío si showLogs es false. Ver tabla abajo.

Campos dentro de cada elemento de events

Campo	Tipo	Descripción
created	String	Fecha y hora en que se detectó el evento (ISO 8601, UTC).
type	String	Tipo de evento riesgoso. Valores: speeding, phoneDistraction, acceleration, deacceleration, cornering.
lat	Number	Latitud del punto donde ocurrió el evento (grados decimales).
lon	Number	Longitud del punto donde ocurrió el evento (grados decimales).
country	String	País donde ocurrió el evento. Puede estar vacío si no se pudo resolver.
state	String	Estado/provincia donde ocurrió el evento. Puede estar vacío si no se pudo resolver.
value	Number	Magnitud cruda del evento. Su unidad depende del type: segundos de distracción para phoneDistraction, fuerza G para acceleration/deacceleration/cornering, 0 para speeding (usa speedViolation).
legalSpeedLimit	Number	Límite legal de velocidad en ese punto (km/h). Sólo en eventos speeding. Es 999 cuando no se pudo obtener el límite real de la vía.
speedLimit	Number	Límite de velocidad efectivamente aplicado al evaluar el evento. Sólo en eventos speeding. Normalmente igual a legalSpeedLimit, salvo cuando la empresa haya configurado un límite personalizado (ver hasCustomSpeedLimit).
speedViolation	Number	Excedente de velocidad sobre speedLimit, en km/h. Sólo en eventos speeding.
hasCustomSpeedLimit	Boolean	true si el límite aplicado proviene de una regla personalizada de la empresa (en lugar del límite legal). Sólo en eventos speeding.

Campos dentro de cada elemento de locationLogs

Campo	Tipo	Descripción
created	String	Fecha y hora del registro (ISO 8601, UTC). La frecuencia de muestreo puede variar entre 1 y 6 segundos.
lat	Number	Latitud del punto (grados decimales).
lon	Number	Longitud del punto (grados decimales).
speed	Number	Velocidad instantánea del conductor, en km/h.
speedLimit	Number	Límite de velocidad del tramo en km/h. Será 999 cuando no se pudo determinar el límite real de la vía.
speedViolation	Number	Excedente sobre speedLimit en km/h. Es 0 cuando no hubo violación o el límite es 999.
distracted	Boolean	true si en ese punto se detectó que el conductor estaba usando el celular.

❌ Respuesta con error (404 Not Found)

Se devuelve cuando el viaje no existe o no pertenece al conductor indicado, cuando el conductor no existe, o cuando showEvents o showLogs no son booleanos. message indica la causa.

{
  "status": true,
  "message": "Error: Trip 8PJbFlQm3kZ2xT0aYc1d does not exist"
}

Causa	message
Viaje inexistente o de otro conductor	"Error: Trip <TRIP_ID> does not exist"
Conductor inexistente	"Error: Driver not found"
showEvents no booleano	"Error: showEvents must be boolean (true|false)"
showLogs no booleano	"Error: showLogs must be boolean (true|false)"

nota

En esta respuesta de error status es true. Usa el código HTTP 404 para detectar el error.