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. Results can be grouped by device or segmented by driver.

• Driver segmentation — drivers parameter filters by specific drivers
• Device grouping — group_by_device=true aggregates by vehicle
• Efficiency metric — average consumption per km for benchmarking

---

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	Aggregate results by vehicle
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_consumption_per_km} L/km`);
}

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_consumption_per_km']} L/km")

---

Response Fields

Field	Type	Description
device_id	string | null	Device identifier
device_name	string	Display name of the vehicle/device
driver_id	string | null	Driver identifier
driver_name	string	Assigned driver name
date	string | null	Date of the record
kms_traveled	number	Total kilometers traveled
fuel_liters	number	Total fuel consumed (liters)
fuel_cost	number	Estimated fuel cost
avg_consumption_per_km	number	Average fuel consumption per kilometer (L/km)

tip

fuel_liters, fuel_cost, and avg_consumption_per_km depend on the fuel consumption rate configured per vehicle. If not configured, these return 0.

Example Response

{
  "success": true,
  "data": [
    {
      "device_id": "104820579301",
      "device_name": "Truck A-101",
      "driver_id": "104820579455",
      "driver_name": "Carlos Martinez",
      "date": "2026-03-05",
      "kms_traveled": 267.7,
      "fuel_liters": 32.12,
      "fuel_cost": 48.18,
      "avg_consumption_per_km": 0.12
    },
    {
      "device_id": "104820579315",
      "device_name": "Van B-205",
      "driver_id": "104820579460",
      "driver_name": "Maria Lopez",
      "date": "2026-03-05",
      "kms_traveled": 142.3,
      "fuel_liters": 11.38,
      "fuel_cost": 17.07,
      "avg_consumption_per_km": 0.08
    }
  ],
  "meta": {
    "total": 84,
    "limit": 50,
    "offset": 0
  }
}

---

Errors

Code	HTTP	Description
BAD_REQUEST	400	Missing required headers
VALIDATION_ERROR	400	Invalid params: missing dates, range > 31 days, limit > 100
UNAUTHORIZED	401	Invalid or expired JWT / 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