Task Kilometers Report

Distance metrics per task grouping — total, average, max, and per-task kilometers.

GET/apidev/v1/reports/gt/gt-kilometers

PermissionAPICLI_RPTGT_KM

Rate Limit10 req/min (sliding window)

Cache300s (5 min)

Max Range31 days

---

Overview

Returns distance metrics per task grouping — total, average, and maximum kilometers, plus a per-task ratio — aggregated by a chosen grouping dimension. Use it to track how far tasks travel and compare mileage across devices, drivers, or zones.

• Grouping — group_by picks the dimension each row represents (see the values below)
• Date basis — the date range always filters on the task finished date (startdate/enddate)
• Filtering — narrow results by devices, drivers, service types, providers, and other catalog filters

---

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
service_types	string	No	All	Comma-separated service type IDs. Max 100
causes	string	No	All	Comma-separated cause IDs. Max 100
subcauses	string	No	All	Comma-separated subcause IDs. Max 100
statuses	string	No	All	Comma-separated status codes. Max 100
device_groups	string	No	All	Comma-separated device type IDs (the device_group catalog from Fleet / Devices). Filters tasks to devices of those types; combines with devices as an intersection. Max 100
origins	string	No	All	Comma-separated origin IDs. Max 100
providers	string	No	All	Comma-separated provider IDs. Max 100
route_ids	string	No	All	Comma-separated route IDs. Max 100
operators	string	No	All	Comma-separated operator IDs. Max 100
client_id	string	No	—	Filter by specific client
account_id	string	No	—	Filter by specific account
shift_id	string	No	—	Filter by specific shift
group_by	enum	No	—	Grouping dimension (see below)
limit	integer	No	25	Records per page (1–100)
offset	integer	No	0	Records to skip

How device_groups combines with devices

device_groups is expanded to every device of those types, and if you also send devices, only the devices present in both lists are kept. If that intersection is empty the report returns no rows.

group_by values

date · month · hour · weekday · department · city · zone · provider · device · device_group · driver · shift · cause · subcause · end_code · origin · telephonist · operator

---

Code Examples

cURL

curl -s -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT" \
  "https://$TENANT/apidev/v1/reports/gt/gt-kilometers?startdate=2026-03-01T00:00:00&enddate=2026-03-31T23:59:59&group_by=device&limit=25"

JavaScript

const headers = {
  'Authorization': `Bearer ${TOKEN}`,
  'X-API-Key': APIKEY,
  'tenant': TENANT,
};

const res = await fetch(
  `https://${TENANT}/apidev/v1/reports/gt/gt-kilometers?startdate=2026-03-01T00:00:00&enddate=2026-03-31T23:59:59&group_by=device&limit=25`,
  { headers }
);
const data = await res.json();

Python

import requests

headers = {
    "Authorization": f"Bearer {TOKEN}",
    "X-API-Key": APIKEY,
    "tenant": TENANT,
}

response = requests.get(
    f"https://{TENANT}/apidev/v1/reports/gt/gt-kilometers",
    headers=headers,
    params={
        "startdate": "2026-03-01T00:00:00",
        "enddate": "2026-03-31T23:59:59",
        "group_by": "device",
        "limit": 25,
    },
)
data = response.json()

---

Response Fields

Field	Type	Description
group_label	string	Display name of the group
group_id	string | null	Identifier of the group element
total_tasks	number	Total number of tasks
total_kms	number	Total kilometers across all tasks
avg_kms	number	Average kilometers per task
max_kms	number	Maximum kilometers for a single task
kms_per_task	number	Kilometers per task ratio

Example Response

{
  "success": true,
  "data": [
    {
      "group_label": "Truck A-101",
      "group_id": "104820579301",
      "total_tasks": 47,
      "total_kms": 892.3,
      "avg_kms": 18.98,
      "max_kms": 45.2,
      "kms_per_task": 18.98
    },
    {
      "group_label": "Truck B-205",
      "group_id": "104820579402",
      "total_tasks": 32,
      "total_kms": 614.7,
      "avg_kms": 19.21,
      "max_kms": 52.8,
      "kms_per_task": 19.21
    }
  ],
  "meta": {
    "total": 2,
    "limit": 25,
    "offset": 0
  }
}

---

Errors

Code	HTTP	Description
VALIDATION_ERROR	400	Invalid params: missing dates, range > 31 days, invalid group_by
UNAUTHORIZED	401	Missing, invalid, or expired tenant / Authorization / X-API-Key
FORBIDDEN	403	User lacks required permission
RATE_LIMITED	429	Exceeded 10 req/min
INTERNAL_ERROR	500	Unexpected server error

---

Related

• Quantity of Services
• Total Service Time
• Arrival Time
• Delay Bands
• Pagination