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

---

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 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['fuel']} L")

---

Response Fields

Field	Type	Description
device_name	string	Display name of the vehicle/device
person_name	string	Assigned driver name. Only populated when perperson=true
state	string	State name. Only populated when groupbygeo is used
city	string	City name. Only populated when groupbygeo=city or neighbourhood
neighbourhood	string	Neighbourhood name. Only populated when groupbygeo=neighbourhood
datetime	string | null	Date of the record (YYYY-MM-DD). Only populated when perday=true
kms	number	Total kilometers traveled
temperature	number	Average temperature sensor 1 reading (°C). 0 if the vehicle has no sensor
fuel	number	Estimated fuel consumed (liters)
cost	number	Estimated fuel cost (currency per vehicle config)
co2	number	Estimated CO₂ emissions (kg)

Fuel and cost values

fuel, 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",
      "person_name": "",
      "state": "",
      "city": "",
      "neighbourhood": "",
      "datetime": "2026-03-01",
      "kms": 267.7,
      "temperature": 22.3,
      "fuel": 32.12,
      "cost": 48.18,
      "co2": 83.54
    },
    {
      "device_name": "Van B-205",
      "person_name": "",
      "state": "",
      "city": "",
      "neighbourhood": "",
      "datetime": "2026-03-01",
      "kms": 142.3,
      "temperature": 4.1,
      "fuel": 11.38,
      "cost": 17.07,
      "co2": 29.57
    }
  ],
  "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",
  "person_name": "Carlos Martinez",
  "state": "",
  "city": "",
  "neighbourhood": "",
  "datetime": "2026-03-01",
  "kms": 180.5,
  "temperature": 22.3,
  "fuel": 21.66,
  "cost": 32.49,
  "co2": 56.32
}

With groupbygeo=state

Geographic subdivision populates the corresponding geo field:

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

---

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