Idle Report

Vehicle idle time analysis — engine-on idle and engine-off stops with geofence and POI context.

GET/apidev/v1/reports/avl/idle

PermissionAPICLI_RPTAVL_DETENIDO

Rate Limit10 req/min (sliding window)

Cache300s (5 min)

Max Range31 days

---

Overview

Detailed breakdown of every period a vehicle was stationary, classified by ignition state.

• Ignition filtering — ignition isolates engine-on idle (fuel waste) vs engine-off stops
• Geofence context — geofences restricts to specific zones
• Duration threshold — idle_min excludes brief stops
• Subtotals — subtotals=true for aggregated summaries

---

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
geofences	string	No	All	Comma-separated geofence IDs. Max 500
idle_min	integer	No	0	Minimum idle time in minutes
ignition	enum	No	All states	Filter by ignition state: on (engine-on stops only), off (engine-off stops only). Omit for all stops
subtotals	boolean	No	false	Include subtotal rows
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/idle?startdate=2026-03-01T00:00:00&enddate=2026-03-15T23:59:59&limit=50&ignition=on" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT"

JavaScript

const response = await fetch(
  `https://${TENANT}/apidev/v1/reports/avl/idle?startdate=2026-03-01T00:00:00&enddate=2026-03-15T23:59:59&limit=50&ignition=on`,
  { headers }
);
const { data, meta } = await response.json();

Python

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

---

Response Fields

Field	Type	Description
device_name	string	Display name of the vehicle/device
person_name	string	Assigned driver at the time of the event. Empty string if none
address	string	Reverse-geocoded address of the idle location
datetime_start	string | null	Timestamp when the idle period started
datetime_end	string | null	Timestamp when the idle period ended
idle_min	number	Duration of the idle period in minutes
type	string	Ignition state during the stop: Apagada (off) or Encendida (on)
geofences	string	Geofence names the idle location falls within. Empty string if none
pois	string	Nearby points of interest. Empty string if none

Example Response

{
  "success": true,
  "data": [
    {
      "device_name": "Van B-205",
      "person_name": "Carlos Medina",
      "address": "Av. 18 de Julio 1234, Montevideo",
      "datetime_start": "2026-03-10T11:05:00",
      "datetime_end": "2026-03-10T11:47:00",
      "idle_min": 42,
      "type": "Encendida",
      "geofences": "Client Zone A",
      "pois": ""
    },
    {
      "device_name": "Truck A-101",
      "person_name": "Ana Lopez",
      "address": "Camino Carrasco 4500, Montevideo",
      "datetime_start": "2026-03-07T16:18:14",
      "datetime_end": "2026-03-07T21:18:12",
      "idle_min": 300,
      "type": "Apagada",
      "geofences": "",
      "pois": "Deposito Central"
    }
  ],
  "meta": {
    "total": 38,
    "limit": 50,
    "offset": 0
  }
}

---

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, invalid ignition value
UNAUTHORIZED	401	Missing, invalid, or expired tenant / Authorization / X-API-Key
FORBIDDEN	403	User lacks APICLI_RPTAVL_DETENIDO permission
RATE_LIMITED	429	Exceeded 10 req/min
INTERNAL_ERROR	500	Unexpected server error

---

Related

• Ignition Report — Engine hours and horometer tracking
• Geofence Report — Entry/exit events by zone
• Pagination — Standard pagination parameters