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

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​