Vehicle Performance Report

Fuel performance analysis — distance, fuel consumption, cost, and efficiency per vehicle or driver.

GET/apidev/v1/reports/avl/vehicle-performance

PermissionAPICLI_RPTAVL_RENDIMIENTO

Rate Limit10 req/min (sliding window)

Cache300s (5 min)

Max Range31 days

---

Overview

Combines distance traveled, fuel consumption, cost, and efficiency into a single report. Metrics are calculated from the fuel refills registered for each vehicle within the date range.

• Driver segmentation — drivers parameter filters by specific drivers
• Driver grouping — group_by_device=true groups results by vehicle + driver instead of vehicle only
• Efficiency metric — average consumption (km per liter) for benchmarking

At least 2 refills required

Performance is derived from the fuel refills recorded for each vehicle. A vehicle needs at least 2 refills within the date range to produce metrics — with a single refill the values are 0.

---

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
enddate	string	Yes	—	ISO 8601 end date-time. Max range 31 days
devices	string	No	All visible	Comma-separated device IDs. Max 500
drivers	string	No	All	Comma-separated driver IDs. Max 500
group_by_device	boolean	No	false	Group results by vehicle + driver instead of vehicle only
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/vehicle-performance?startdate=2026-03-01T00:00:00&enddate=2026-03-15T23:59:59&limit=50&group_by_device=true" \
  -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",
  group_by_device: "true",
});

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

const { data, meta } = await response.json();
for (const row of data) {
  console.log(`${row.device_name}: ${row.kms_traveled} km — ${row.fuel_liters} L — ${row.avg_km_per_liter} km/L`);
}

Python

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

result = response.json()
for row in result["data"]:
    print(f"{row['device_name']}: {row['kms_traveled']} km — {row['avg_km_per_liter']} km/L")

---

Response Fields

Field	Type	Description
device_name	string	Display name of the vehicle/device
driver_name	string	Assigned driver name (relevant with group_by_device=true)
kms_traveled	number	Kilometers traveled between refills
fuel_liters	number	Liters loaded (from registered refills)
fuel_cost	number	Total refill amount
avg_km_per_liter	number	Average consumption (km per liter)

tip

Values come from the fuel refills registered for each vehicle within the range — a vehicle without at least 2 refills in the range returns 0 for all metrics.

Example Response

{
  "success": true,
  "data": [
    {
      "device_name": "Truck A-101",
      "driver_name": "Carlos Martinez",
      "kms_traveled": 267.7,
      "fuel_liters": 32.12,
      "fuel_cost": 48.18,
      "avg_km_per_liter": 8.33
    },
    {
      "device_name": "Van B-205",
      "driver_name": "Maria Lopez",
      "kms_traveled": 142.3,
      "fuel_liters": 11.38,
      "fuel_cost": 17.07,
      "avg_km_per_liter": 12.5
    }
  ],
  "meta": {
    "total": 84,
    "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
UNAUTHORIZED	401	Missing, invalid, or expired tenant / Authorization / X-API-Key
FORBIDDEN	403	User lacks APICLI_RPTAVL_RENDIMIENTO permission
RATE_LIMITED	429	Exceeded 10 req/min
INTERNAL_ERROR	500	Unexpected server error

---

Related

• Kilometers Report — Distance and consumption aggregates
• Ignition Report — Engine hours tracking
• Drivers API — Get driver IDs to filter
• Pagination — Standard pagination parameters