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
Stop evidence — each stop says whether the engine was on, what ended it, and how solid the signal was (engine, ended_by, points, max_silence_seconds, radius_m, reappeared_far)

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 engine state: `on` (engine-on stops only), `off` (engine-off stops — for backward compatibility this also includes stops with no engine data), `unknown` (only stops with no engine data). Omit for all stops
`subtotals`	boolean	No	`false`	Ignored. Still accepted so existing calls keep working, but the endpoint never returns subtotal or grand-total rows
`limit`	integer	No	`25`	Records per page (`1`–`100`)
`offset`	integer	No	`0`	Records to skip

No summary rows

Every row in data is one stop. Subtotal and grand-total rows are never returned (not even with subtotals=true), so you can sum idle_min yourself without double-counting. meta.total counts stops.

Code Examples

cURL
JavaScript
Python

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"

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();

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. `null` when the stop is `open`
`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
`engine`	string \| null	Engine state during the stop: `off`, `on` or `unknown` (the device sent no engine data)
`ended_by`	string \| null	What ended the stop: `movement` (the vehicle started moving), `engine_on` (the engine was switched on; if the vehicle did not move, a new stop with the engine on starts at the same place), `engine_off` (the engine was switched off without moving; a new stop with the engine off starts at the same place), `drift` (it moved away from where it stopped). For an open stop: `day_end` = a stop from a previous day that was still going when that day ended (the next day has its own row); `null` = a stop from today, the vehicle is still stopped
`open`	boolean \| null	`true` when the stop had not ended within its day (see `ended_by`); `datetime_end` is then `null`
`points`	integer \| null	Stationary positions that back the stop
`max_silence_seconds`	integer \| null	Longest gap without reports during the stop (including the one right before it ended), in seconds
`radius_m`	integer \| null	Farthest distance from where the vehicle stopped, in meters
`reappeared_far`	boolean \| null	`true` when the device went silent and reappeared far away: the stop was closed at the last stationary report and the time without signal was not counted

Stops not yet reprocessed

The engine-state and evidence fields (engine through reappeared_far) come from the current stop-detection engine. Stops calculated before it and not yet reprocessed return all of them as null; their other fields are unchanged. Stops never cross midnight: a stop is reported on the day it started.

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": "",
      "engine": "on",
      "ended_by": "movement",
      "open": false,
      "points": 9,
      "max_silence_seconds": 300,
      "radius_m": 12,
      "reappeared_far": false
    },
    {
      "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",
      "engine": "off",
      "ended_by": "engine_on",
      "open": false,
      "points": 3,
      "max_silence_seconds": 4250,
      "radius_m": 15,
      "reappeared_far": false
    }
  ],
  "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

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

Overview​

Request​

Request Headers​

Query Parameters​

Code Examples​

Response Fields​

Example Response​

Errors​

Related​