Kilometers Report

Distance traveled, fuel consumption, and cost metrics for your fleet over a given period.

GET/apidev/v1/reports/avl/kilometers

PermissionAPICLI_RPTAVL_KILOMETROS

Rate Limit10 req/min (sliding window)

Cache300s (5 min)

Max Range31 days

---

Overview

Provides distance and consumption data for every vehicle in your fleet. Use it to audit mileage, estimate fuel costs, and track CO₂ emissions.

• Daily breakdown — perday=true returns one row per vehicle per day
• Driver grouping — perperson=true segments results by the assigned driver
• Geographic subdivision — groupbygeo splits totals by state, city, or neighbourhood
• Subtotals — subtotals=true includes 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 from startdate
devices	string	No	All visible	Comma-separated device IDs. Max 500
limit	integer	No	25	Records per page (1–100)
offset	integer	No	0	Records to skip
perday	boolean	No	false	Group results by day
perperson	boolean	No	false	Group results by assigned driver
subtotals	boolean	No	false	Include subtotal rows
groupbygeo	enum	No	—	Subdivide by area: state, city, or neighbourhood

Device visibility

When devices is omitted, the report includes all devices visible to the authenticated user based on their permission scope.

---

Code Examples

cURL

curl -s "https://$TENANT/apidev/v1/reports/avl/kilometers?startdate=2026-03-01T00:00:00&enddate=2026-03-15T23:59:59&limit=50&perday=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",
  perday: "true",
});

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

const { data, meta } = await response.json();
console.log(`${data.length} rows of ${meta.total}`);

Python

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

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

---

Response Fields

Field	Type	Description
device_name	string	Display name of the vehicle/device
device_group	string	Group the device belongs to
person_name	string | null	Assigned driver name (when perperson is enabled)
datetime	string | null	Date of the record (when perday is enabled)
kms	number	Total kilometers traveled
gas	number	Estimated fuel consumed (liters)
cost	number	Estimated fuel cost (currency per vehicle config)
co2	number	Estimated CO₂ emissions (kg)
temperature	number	Average temperature sensor reading
state	string | null	State name (when groupbygeo is used)
city	string | null	City name (when groupbygeo is used)
neighbourhood	string | null	Neighbourhood name (when groupbygeo is used)

Fuel and cost values

gas, cost, and co2 are calculated using the fuel consumption rate and fuel price configured in each vehicle's settings. If not configured, these fields return 0.

Example Response

{
  "success": true,
  "data": [
    {
      "device_name": "Truck A-101",
      "device_group": "Logistics North",
      "person_name": null,
      "datetime": "2026-03-01",
      "kms": 267.7,
      "gas": 32.12,
      "cost": 48.18,
      "co2": 83.54,
      "temperature": 22.3,
      "state": null,
      "city": null,
      "neighbourhood": null
    },
    {
      "device_name": "Van B-205",
      "device_group": "Urban Delivery",
      "person_name": null,
      "datetime": "2026-03-01",
      "kms": 142.3,
      "gas": 11.38,
      "cost": 17.07,
      "co2": 29.57,
      "temperature": 4.1,
      "state": null,
      "city": null,
      "neighbourhood": null
    }
  ],
  "meta": {
    "total": 84,
    "limit": 50,
    "offset": 0
  }
}

With perperson=true

When driver grouping is enabled, person_name is populated and multiple rows may appear for the same device if drivers changed during the period:

{
  "device_name": "Truck A-101",
  "device_group": "Logistics North",
  "person_name": "Carlos Martinez",
  "datetime": "2026-03-01",
  "kms": 180.5,
  "gas": 21.66,
  "cost": 32.49,
  "co2": 56.32,
  "temperature": 22.3,
  "state": null,
  "city": null,
  "neighbourhood": null
}

With groupbygeo=state

Geographic subdivision populates the corresponding geo field:

{
  "device_name": "Truck A-101",
  "device_group": "Logistics North",
  "person_name": null,
  "datetime": null,
  "kms": 180.5,
  "gas": 21.66,
  "cost": 32.49,
  "co2": 56.32,
  "temperature": 0,
  "state": "Montevideo",
  "city": null,
  "neighbourhood": null
}

---

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_KILOMETROS permission
RATE_LIMITED	429	Exceeded 10 req/min
INTERNAL_ERROR	500	Unexpected server error

---

Related

• Rate Limits — Sliding window details
• Pagination — Standard pagination parameters
• Devices API — Get device IDs to filter reports