Trips Report

Individual trip records with origin, destination, distance, duration, and fuel consumption per vehicle journey.

GET/apidev/v1/reports/avl/trips

PermissionAPICLI_RPTAVL_VIAJES

Rate Limit10 req/min (sliding window)

Cache300s (5 min)

Max Range31 days

---

Overview

Breaks down vehicle activity into individual trips. A trip begins when a vehicle starts moving and ends when it remains stopped for a configurable duration.

• Custom stop threshold — idle_min defines the minimum stop time that marks the end of a trip
• Micro-movement filtering — duration_min excludes short trips caused by GPS jitter or parking maneuvers
• Subtotals — subtotals=true includes aggregated summary rows

---

Query Parameters

Parameter	Type	Required	Default	Description
startdate	string	Yes	—	ISO 8601 start date-time (e.g. 2026-03-01T00:00:00)
enddate	string	Yes	—	ISO 8601 end date-time. Max range 31 days
devices	string	No	All visible	Comma-separated device IDs. Max 500
idle_min	integer	No	0	Minimum stop time in minutes to end a trip
duration_min	integer	No	0	Minimum trip duration in minutes. Shorter trips are excluded
subtotals	boolean	No	false	Include subtotal rows
limit	integer	No	25	Records per page (1–100)
offset	integer	No	0	Records to skip

---

Code Examples

cURL

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"

JavaScript

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)`);
}

Python

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

---

Response Fields

Field	Type	Description
device_name	string	Display name of the vehicle/device
trip_start	string | null	Timestamp when the trip started
trip_start_address	string | null	Reverse-geocoded address of the origin
trip_start_lat	number | null	Latitude of the origin
trip_start_lon	number | null	Longitude of the origin
trip_end	string | null	Timestamp when the trip ended
trip_end_address	string | null	Reverse-geocoded address of the destination
trip_end_lat	number | null	Latitude of the destination
trip_end_lon	number | null	Longitude of the destination
kms	number	Distance traveled (km)
duration_min	number	Trip duration in minutes
idle_min	number	Idle time during the trip in minutes
max_speed	number	Maximum speed recorded (km/h)
fuel	number	Estimated fuel consumed (liters)
cost	number	Estimated fuel cost

Fuel and cost

fuel and cost are calculated using the consumption rate and fuel price configured per vehicle. If not configured, these return 0.

Example Response

{
  "success": true,
  "data": [
    {
      "device_name": "Truck A-101",
      "trip_start": "2026-03-05T07:15:00",
      "trip_start_address": "Av. 18 de Julio 1234, Montevideo",
      "trip_start_lat": -34.9011,
      "trip_start_lon": -56.1645,
      "trip_end": "2026-03-05T09:42:00",
      "trip_end_address": "Ruta 1 km 42, San Jose",
      "trip_end_lat": -34.3426,
      "trip_end_lon": -56.7135,
      "kms": 38.5,
      "duration_min": 147,
      "idle_min": 12,
      "max_speed": 95,
      "fuel": 4.62,
      "cost": 6.93
    },
    {
      "device_name": "Van B-205",
      "trip_start": "2026-03-05T10:05:00",
      "trip_start_address": "Bulevar Artigas 1550, Montevideo",
      "trip_start_lat": -34.8941,
      "trip_start_lon": -56.1592,
      "trip_end": "2026-03-05T10:38:00",
      "trip_end_address": "Av. Italia 3210, Montevideo",
      "trip_end_lat": -34.8763,
      "trip_end_lon": -56.1284,
      "kms": 8.2,
      "duration_min": 33,
      "idle_min": 5,
      "max_speed": 58,
      "fuel": 0.98,
      "cost": 1.47
    }
  ],
  "meta": {
    "total": 156,
    "limit": 50,
    "offset": 0
  }
}

---

Errors

Code	HTTP	Description
BAD_REQUEST	400	Missing required headers
VALIDATION_ERROR	400	Invalid params: missing dates, range > 31 days, malformed ISO date, limit > 100, > 500 devices
UNAUTHORIZED	401	Invalid or expired JWT / API Key
FORBIDDEN	403	User lacks APICLI_RPTAVL_VIAJES permission
RATE_LIMITED	429	Exceeded 10 req/min
INTERNAL_ERROR	500	Unexpected server error

---

Related

• Kilometers Report — Aggregated distance and fuel per vehicle
• Idle Report — Detailed idle/stop analysis
• Rate Limits — Sliding window details
• Pagination — Standard pagination parameters