Reporte de Viajes

Registros de viajes individuales con origen, destino, distancia, duración y consumo de combustible por trayecto de vehículo.

GET/apidev/v1/reports/avl/trips

PermisoAPICLI_RPTAVL_VIAJES

Límite de solicitudes10 req/min (ventana deslizante)

Caché300s (5 min)

Rango máximo31 días

Resumen

Desglosa la actividad del vehículo en viajes individuales. Un viaje comienza cuando un vehículo empieza a moverse y termina cuando permanece detenido durante una duración configurable.

Umbral de parada personalizado — idle_min define el tiempo mínimo de parada que marca el fin de un viaje
Filtrado de micromovimientos — duration_min excluye viajes cortos causados por ruido del GPS o maniobras de estacionamiento
Subtotales — subtotals=true incluye filas de resumen agregadas

Solicitud

Encabezados de la solicitud

Every request to a protected endpoint requires these headers:

Header	Required	Description
`Authorization`	Yes	Bearer token obtained from the Login endpoint. Format: `Bearer <token>`
`X-API-Key`	Yes	Company integration key provided during onboarding. Format: `gtk_xxx...`
`tenant`	Yes	Your assigned tenant domain (default: `geotareas.com`) — always send your assigned tenant
`Content-Type`	Conditional	`application/json` — required for `POST` and `PUT` requests

Parámetros de consulta

Parámetro	Tipo	Requerido	Predeterminado	Descripción
`startdate`	string	Sí	—	Fecha-hora de inicio en ISO 8601 (ej. `2026-03-01T00:00:00`)
`enddate`	string	Sí	—	Fecha-hora de fin en ISO 8601. Rango máximo 31 días
`devices`	string	No	Todos los visibles	IDs de dispositivo separados por coma. Máximo 500
`idle_min`	integer	No	`0`	Tiempo mínimo de parada en minutos para finalizar un viaje
`duration_min`	integer	No	`0`	Duración mínima del viaje en minutos. Los viajes más cortos se excluyen
`subtotals`	boolean	No	`false`	Incluye filas de subtotal
`limit`	integer	No	`25`	Registros por página (`1`–`100`)
`offset`	integer	No	`0`	Registros a omitir

Con subtotals=true cambia el comportamiento de limit

Las filas de subtotal y de total general se agregan después de haber cortado la página, y recién ahí el resultado se recorta a limit. O sea que con subtotals=true la respuesta sigue trayendo como máximo limit filas, pero parte de ese cupo se va en filas de resumen — vas a recibir menos filas de detalle que en una página normal del mismo tamaño.

Las filas de resumen no vienen marcadas en la respuesta. La única forma de reconocerlas es por device_name: un subtotal por móvil dice "<nombre del móvil> (subtotal)" y el total general dice "Total general". Si estás sumando los datos por tu cuenta, filtrá esas filas o vas a contar dos veces.

meta.total cuenta siempre solo las filas de detalle. Para paginar limpio, dejá subtotals apagado y calculá tus propios totales.

Ejemplos de código

cURL
JavaScript
Python

curl -s "https://$TENANT/apidev/v1/reports/avl/trips?startdate=2026-03-01T00:00:00&enddate=2026-03-15T23:59:59&limit=50&idle_min=5" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT"

const params = new URLSearchParams({
  startdate: "2026-03-01T00:00:00",
  enddate: "2026-03-15T23:59:59",
  limit: "50",
  idle_min: "5",
});

const response = await fetch(
  `https://${TENANT}/apidev/v1/reports/avl/trips?${params}`,
  { headers }
);

const { data, meta } = await response.json();
for (const trip of data) {
  console.log(`${trip.device_name}: ${trip.trip_start_address} → ${trip.trip_end_address} (${trip.kms} km)`);
}

response = requests.get(
    f"https://{TENANT}/apidev/v1/reports/avl/trips",
    headers=headers,
    params={
        "startdate": "2026-03-01T00:00:00",
        "enddate": "2026-03-15T23:59:59",
        "limit": 50,
        "idle_min": 5,
    },
)

result = response.json()
for trip in result["data"]:
    print(f"{trip['device_name']}: {trip['kms']} km in {trip['duration_min']} min")

Campos de la respuesta

Campo	Tipo	Descripción
`device_name`	string	Nombre visible del vehículo/dispositivo
`person_name`	string	Conductores del viaje (nombres; cadena vacía si no hay)
`trip_start`	string \| null	Marca de tiempo de cuando comenzó el viaje
`trip_start_address`	string \| null	Dirección geocodificada inversa del origen
`trip_end`	string \| null	Marca de tiempo de cuando terminó el viaje
`trip_end_address`	string \| null	Dirección geocodificada inversa del destino
`kms`	number	Distancia recorrida (km)
`duration_min`	number	Duración del viaje en minutos
`idle_min`	number	Tiempo detenido durante el viaje en minutos
`max_speed`	number	Velocidad máxima registrada (km/h)
`fuel`	number	Combustible consumido estimado (litros)
`cost`	number	Costo de combustible estimado
`temperature`	number	Lectura del sensor de temperatura 1. `0` si el vehículo no tiene sensor

Combustible y costo

fuel y cost se calculan usando la tasa de consumo y el precio de combustible configurados por vehículo. Si no están configurados, estos devuelven 0.

Ejemplo de respuesta

{
  "success": true,
  "data": [
    {
      "device_name": "Truck A-101",
      "person_name": "Carlos Martinez",
      "trip_start": "2026-03-05T07:15:00",
      "trip_start_address": "Av. 18 de Julio 1234, Montevideo",
      "trip_end": "2026-03-05T09:42:00",
      "trip_end_address": "Ruta 1 km 42, San Jose",
      "kms": 38.5,
      "duration_min": 147,
      "idle_min": 12,
      "max_speed": 95,
      "fuel": 4.62,
      "cost": 6.93,
      "temperature": 0
    },
    {
      "device_name": "Van B-205",
      "person_name": "Ana Lopez",
      "trip_start": "2026-03-05T10:05:00",
      "trip_start_address": "Bulevar Artigas 1550, Montevideo",
      "trip_end": "2026-03-05T10:38:00",
      "trip_end_address": "Av. Italia 3210, Montevideo",
      "kms": 8.2,
      "duration_min": 33,
      "idle_min": 5,
      "max_speed": 58,
      "fuel": 0.98,
      "cost": 1.47,
      "temperature": -2.5
    }
  ],
  "meta": {
    "total": 156,
    "limit": 50,
    "offset": 0
  }
}

Errores

Código	HTTP	Descripción
`INVALID_DATE_RANGE`	400	El rango de fechas supera el máximo de 31 días, el fin es anterior al inicio, o fechas no ISO
`VALIDATION_ERROR`	400	Parámetros inválidos: faltan fechas, `limit` > 100, > 500 dispositivos
`UNAUTHORIZED`	401	tenant / Authorization / X-API-Key faltante, inválido o expirado
`FORBIDDEN`	403	El usuario carece del permiso `APICLI_RPTAVL_VIAJES`
`RATE_LIMITED`	429	Se superaron las 10 req/min
`INTERNAL_ERROR`	500	Error inesperado del servidor

Reporte de Kilómetros — Distancia y combustible agregados por vehículo
Reporte de Detenido — Análisis detallado de inactividad/paradas
Límites de solicitudes — Detalles de la ventana deslizante
Paginación — Parámetros de paginación estándar

Resumen​

Solicitud​

Encabezados de la solicitud​

Parámetros de consulta​

Ejemplos de código​

Campos de la respuesta​

Ejemplo de respuesta​

Errores​

Relacionado​