Idle Report

Vehicle idle time analysis — engine-on idle, engine-off stops, and signal loss periods with geofence 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

---

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	Filter by ignition state: all, on, off
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
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	Idle type description (e.g. engine on, engine off, no signal)
address	string	Reverse-geocoded address of the idle location
latitude	number | null	Latitude of the idle location
longitude	number | null	Longitude of the idle location
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",
      "datetime_start": "2026-03-10T11:05:00",
      "datetime_end": "2026-03-10T11:47:00",
      "idle_min": 42,
      "type": "Detenido con ignición encendida",
      "address": "Av. 18 de Julio 1234, Montevideo",
      "latitude": -34.9011,
      "longitude": -56.1645,
      "geofences": "Client Zone A",
      "pois": ""
    }
  ],
  "meta": {
    "total": 38,
    "limit": 50,
    "offset": 0
  }
}

---

Errors

Code	HTTP	Description
BAD_REQUEST	400	Missing required headers
VALIDATION_ERROR	400	Invalid params: missing dates, range > 31 days, invalid ignition value
UNAUTHORIZED	401	Invalid or expired JWT / 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