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

---

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

---

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

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