Trips Report
Individual trip records with origin, destination, distance, duration, and fuel consumption per vehicle journey.
/apidev/v1/reports/avl/tripsOverview
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_mindefines the minimum stop time that marks the end of a trip - Micro-movement filtering —
duration_minexcludes short trips caused by GPS jitter or parking maneuvers - Subtotals —
subtotals=trueincludes aggregated summary rows
Request
Request Headers
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 |
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 |
subtotals=true changes how limit behavesThe subtotal and grand-total rows are appended after the page has been cut, and the result is then trimmed back to limit. So with subtotals=true the response still returns at most limit rows, but some of that budget is spent on summary rows — you get fewer detail rows than a plain page of the same size.
Summary rows are not flagged in the payload. You can only recognise them by device_name: a per-device subtotal reads "<device name> (subtotal)" and the grand total reads "Total general". If you are aggregating the data yourself, filter those rows out or you will double-count.
meta.total always counts detail rows only. For a clean paginated read, leave subtotals off and compute your own totals.
Code Examples
- 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")
Response Fields
| Field | Type | Description |
|---|---|---|
device_name | string | Display name of the vehicle/device |
person_name | string | Driver(s) assigned during the trip. Empty string if none |
trip_start | string | null | Timestamp when the trip started |
trip_start_address | string | null | Reverse-geocoded address of the origin |
trip_end | string | null | Timestamp when the trip ended |
trip_end_address | string | null | Reverse-geocoded address 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 during the trip (km/h) |
fuel | number | Estimated fuel consumed (liters). 0 if the vehicle has no consumption rate configured |
cost | number | Estimated fuel cost. 0 if the vehicle has no fuel price configured |
temperature | number | Temperature sensor 1 reading (°C). 0 if the vehicle has no sensor |
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",
"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": 4.1
}
],
"meta": {
"total": 156,
"limit": 50,
"offset": 0
}
}
Errors
| Code | HTTP | Description |
|---|---|---|
INVALID_DATE_RANGE | 400 | Date range exceeds the 31-day maximum, end before start, or non-ISO dates |
VALIDATION_ERROR | 400 | Invalid params: missing dates, limit > 100, > 500 devices |
UNAUTHORIZED | 401 | Missing, invalid, or expired tenant / Authorization / X-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