Fleet Efficiency Report

Operational KPIs per vehicle group — finished-task counts and distance totals, with placeholders for GPS-derived idle and CO2 metrics.

GET/apidev/v1/reports/gt/fleet-efficiency

PermissionAPICLI_RPTGT_EFICIENCIAFLOTA

Rate Limit10 req/min

Cache300s

Max Range92 days

---

Overview

This report returns fleet operational metrics for finished tasks, aggregated per group — by provider, device, driver, service type, cause, geography, date, and more. Each row reports the task count plus distance totals (sum, average, minimum, maximum) over the selected period. Choose how rows are grouped with group_by (defaults to provider).

The idle_ratio_pct and co2_estimado_kg fields are returned as placeholders set to 0. These metrics are derived from raw GPS tracking and are computed in the application layer rather than in this aggregate endpoint, so they are present in the response shape for forward compatibility but are not populated here.

---

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 92 days from startdate.
group_by	string	No	provider	How rows are grouped. One of: provider, device, driver, cause, subcause, service_type, product, origin, shift, end_code, comm_media, route, country, department, city, zone, client, telephonist, operator, resource_type, date, month, weekday, hour.
devices	string	No	—	Comma-separated device IDs. Max 500.
drivers	string	No	—	Comma-separated driver IDs. Max 500.
providers	string	No	—	Comma-separated provider IDs. Max 100.
service_types	string	No	—	Comma-separated service type IDs. Max 100.
causes	string	No	—	Comma-separated cause IDs. Max 100.
subcauses	string	No	—	Comma-separated subcause IDs. Max 100.
statuses	string	No	—	Comma-separated task 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	—	Comma-separated origin IDs. Max 100.
route_ids	string	No	—	Comma-separated route IDs. Max 100.
operators	string	No	—	Comma-separated operator IDs. Max 100.
client_id	string	No	—	Single client ID.
account_id	string	No	—	Single account ID.
shift_id	string	No	—	Single shift ID.
limit	integer	No	25	Number of records per page (1–100).
offset	integer	No	0	Number of records to skip for pagination.

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.

---

Code Examples

cURL

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

JavaScript

const res = await fetch(
  `https://${TENANT}/apidev/v1/reports/gt/fleet-efficiency?startdate=2026-03-01T00:00:00&enddate=2026-03-15T23:59:59&group_by=device&limit=25`,
  {
    headers: {
      'Authorization': `Bearer ${TOKEN}`,
      'X-API-Key': APIKEY,
      'tenant': TENANT,
    },
  }
);
const data = await res.json();

Python

import requests

response = requests.get(
    f"https://{TENANT}/apidev/v1/reports/gt/fleet-efficiency",
    headers={"Authorization": f"Bearer {TOKEN}", "X-API-Key": APIKEY, "tenant": TENANT},
    params={
        "startdate": "2026-03-01T00:00:00",
        "enddate": "2026-03-15T23:59:59",
        "group_by": "device",
        "limit": 25,
    },
)
data = response.json()

---

Response

Response Fields

Field	Type	Description
group_label	string	Display name of the group (e.g. device, driver, provider).
group_id	string | null	Internal ID of the group, or null when not resolvable.
total	number	Total finished tasks in the group.
dist_total	number	Total distance across the group's tasks.
dist_prom	number	Average distance per task.
dist_max	number	Maximum single-task distance.
dist_min	number	Minimum non-zero single-task distance.
idle_ratio_pct	number	Placeholder for GPS-derived idle ratio. Always 0 from this endpoint.
co2_estimado_kg	number	Placeholder for GPS-derived estimated CO2. Always 0 from this endpoint.

Example Response

{
  "success": true,
  "data": [
    {
      "group_label": "Truck A-101",
      "group_id": "55012",
      "total": 138,
      "dist_total": 4210,
      "dist_prom": 31,
      "dist_max": 92,
      "dist_min": 4,
      "idle_ratio_pct": 0,
      "co2_estimado_kg": 0
    }
  ],
  "meta": {
    "total": 1,
    "limit": 25,
    "offset": 0
  }
}

---

Errors

Code	HTTP	Description
VALIDATION_ERROR	400	Invalid params: missing dates, range > 92 days, invalid enum values.
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

• Demand vs Capacity Report
• GT Kilometers Report
• Productivity Report
• Pagination