Consultar los eventos y logs de un viaje

[ POST ]

Devuelve los registros de geolocalización (ruta recorrida) y los eventos riesgosos detectados 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. Si no coincide, devuelve error.
showEvent	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.

• Frenadobraking

  El conductor frenó de manera agresiva.

• Curva agresivacornering

  El conductor tomó una curva con excesiva fuerza lateral.

Headers

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

Body

{
  "driverId": "string",
  "showEvent": "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",
  "showEvent": 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": "speeding",
        "value": 0,
        "legalSpeedLimit": 20,
        "speedLimit": 20,
        "speedViolation": 6.1,
        "hasCustomSpeedLimit": false
      },
      {
        "created": "2025-02-02T20:19:58.000Z",
        "country": "",
        "state": "",
        "lat": 19.42731,
        "lon": -99.17842,
        "type": "phoneDistraction",
        "value": 12.4,
        "legalSpeedLimit": 0,
        "speedLimit": 0,
        "speedViolation": 0,
        "hasCustomSpeedLimit": false
      }
    ],
    "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:11:58.213Z",
        "speed": 22.14,
        "speedLimit": 50,
        "speedViolation": 0,
        "lat": 19.42493,
        "lon": -99.18476
      },
      {
        "distracted": false,
        "created": "2025-02-02T20:13:07.000Z",
        "speed": 38.62,
        "speedLimit": 50,
        "speedViolation": 0,
        "lat": 19.42511,
        "lon": -99.18398
      },
      {
        "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
      },
      {
        "distracted": false,
        "created": "2025-02-02T20:39:02.000Z",
        "speed": 0,
        "speedLimit": 50,
        "speedViolation": 0,
        "lat": 19.42895,
        "lon": -99.17203
      }
      // … (resto de logs de geolocalización del viaje)
    ]
  }
}

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. Sólo se incluye si showEvent es true. Ver tabla abajo.
data.locationLogs	Array<Object>	Registros de geolocalización ordenados cronológicamente. Sólo se incluye si showLogs es true. 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, braking, 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/braking/cornering, 0 para speeding (usa speedViolation).
legalSpeedLimit	Number	Límite legal de velocidad en ese punto (km/h). Aplica sólo a 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. 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. Aplica sólo a eventos speeding.
hasCustomSpeedLimit	Boolean	true si el límite aplicado proviene de una regla personalizada de la empresa (en lugar del límite legal).

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 (400 Bad Request)

Se devuelve cuando el driverId no coincide con el conductor del TRIP_ID solicitado o cuando el viaje no existe.

{
  "status": false,
  "message": "Error: Trip not found for driver",
  "errorId": "sentry_error_id_123"
}

Campos

Nombre	Tipo	Requerido	Descripción
TRIP_ID	String	Si	ID del viaje que desea consultar. Este valor deberá ir en la ruta.
driverId	String	Si	ID del conductor que ejectó el viaje especificado en TRIP_ID, si no lo encuentra regresara con error.
showEvent	Boolean	No	Bandera que determina si quieres ver los eventos riesgosos, por default es True
showLogs	Boolean	No	Bandera que determina si quieres ver los logs de geolocalización, por default es True

Eventos riesgosos

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.

• Frenadobraking

  El conductor frenó de manera agresiva.

• Curva agresivacornering

  El conductor tomó una curva con excesiva fuerza lateral.

Headers

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

Body

{
  "driverId": "string",
  "showEvent": "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",
  "showEvent": true,
  "showLogs": false
}'

Respuesta

Logs de geolocalización

{
  "distracted": "boolean",
  "created": "ISO 8601 Date String",
  "speed": "number",
  "speedLimit": "number",
  "speedViolation": "number",
  "lat": "number",
  "lon": "number"
}

Eventos riesgosos

{
  "created": "string",
  "country": "string",
  "state": "string",
  "lat": "number",
  "lon": "number",
  "type": "string",
  "value": "number",
  "legalSpeedLimit": "number",
  "speedLimit": "number",
  "speedViolation": "number",
  "hasCustomSpeedLimit": "boolean"
}