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

Nombre	Llave	Descripción
Exceso de velocidad	`speeding`	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.
Uso del celular	`phoneDistraction`	El conductor manipuló el celular mientras conducía a una velocidad superior a 15 km/h.
Aceleración	`acceleration`	El conductor aceleró de manera agresiva.
Frenado	`braking`	El conductor frenó de manera agresiva.
Curva agresiva	`cornering`	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

Nombre	Llave	Descripción
Excesos de velocidad	speeding	Determina que la velocidad del condcutor fue mayor a la velocidad permitida por dicha calle, si el limite sale en 999 es porque no conseguimos la información necesaria para esa calle.
Uso del celular	phoneDistraction	Determina si el conductor estuvo usando el celular manejando a una velocidad arriba de 15km/hr.
Acceleración	acceleration	Determina si el conductor aceleró de manera agresiva.
Deacceleración	braking	Determina si el conductor desaceleró de manera agresiva.
Curvas	cornering	Determina si el condcutor tomo una curva de manera agresiva.

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"
}

Campos​

Eventos riesgosos​

Headers​

Body​

Ejemplo​

Respuestas​

✅ Respuesta exitosa (200 OK)​

Descripción de campos de respuesta​

Campos dentro de cada elemento de events​

Campos dentro de cada elemento de locationLogs​

❌ Respuesta con error (400 Bad Request)​

Campos​

Eventos riesgosos​

Headers​

Body​

Ejemplo​

Respuesta​

Logs de geolocalización​

Eventos riesgosos​

Campos

Eventos riesgosos

Headers

Body

Ejemplo

Respuestas

✅ Respuesta exitosa (200 OK)

Descripción de campos de respuesta

Campos dentro de cada elemento de `events`

Campos dentro de cada elemento de `locationLogs`

❌ Respuesta con error (400 Bad Request)

Campos

Eventos riesgosos

Headers

Body

Ejemplo

Respuesta

Logs de geolocalización

Eventos riesgosos