Geofence Report

Vehicle entries and exits across geofenced zones, including dwell time and visit filtering.

GET/apidev/v1/reports/avl/geofence

PermissionAPICLI_RPTAVL_GEOCERCA

Rate Limit10 req/min (sliding window)

Cache300s (5 min)

Max Range31 days

Overview

Returns entry and exit events for vehicles crossing predefined geographic zones (geofences). Each record represents a single visit — from entry to exit.

Zone filtering — restrict to specific geofences with the geofences parameter
Dwell time threshold — use idletime to exclude visits shorter than a minimum duration
Visit analytics — calculate total time spent per zone for route compliance and SLA monitoring

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 31 days
`devices`	string	No	All visible	Comma-separated device IDs. Max 500
`geofences`	string	No	All visible	Comma-separated geofence IDs. Max 500
`idletime`	number	No	`0`	Minimum dwell time in minutes. Visits shorter than this are excluded
`limit`	integer	No	`25`	Records per page (`1`–`100`)
`offset`	integer	No	`0`	Records to skip

Geofence visibility

Only geofences visible to the authenticated user can be queried. Requesting an inaccessible geofence ID returns no data for that zone — no error is raised.

Code Examples

cURL
JavaScript
Python

curl -s "https://$TENANT/apidev/v1/reports/avl/geofence?startdate=2026-03-01T00:00:00&enddate=2026-03-15T23:59:59&limit=50&geofences=101,102,103" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT"

const params = new URLSearchParams({
  startdate: "2026-03-01T00:00:00",
  enddate: "2026-03-15T23:59:59",
  limit: "50",
  geofences: "101,102,103",
});

const response = await fetch(
  `https://${TENANT}/apidev/v1/reports/avl/geofence?${params}`,
  { headers }
);

const { data, meta } = await response.json();
for (const visit of data) {
  console.log(`${visit.device_name} → ${visit.geofence}: ${visit.idle} min`);
}

response = requests.get(
    f"https://{TENANT}/apidev/v1/reports/avl/geofence",
    headers=headers,
    params={
        "startdate": "2026-03-01T00:00:00",
        "enddate": "2026-03-15T23:59:59",
        "limit": 50,
        "geofences": "101,102,103",
    },
)

result = response.json()
for visit in result["data"]:
    print(f"{visit['device_name']} → {visit['geofence']}: {visit['idle']} min")

Response Fields

Field	Type	Description
`device_name`	string	Display name of the vehicle/device
`people`	string	Name of the assigned driver at the time of the visit
`geofence`	string	Name of the geofence zone visited
`datetime_in`	string \| null	Timestamp when the device entered the geofence
`datetime_out`	string \| null	Timestamp when the device exited. `null` if still inside
`idle`	number	Dwell time inside the geofence in minutes

Timestamps

All timestamps are returned without timezone (e.g. "2026-03-05T08:12:33"). See Pagination & Envelope for the standard response wrapper.

Example Response

{
  "success": true,
  "data": [
    {
      "device_name": "Van B-205",
      "people": "Carlos Medina",
      "geofence": "Warehouse Central",
      "datetime_in": "2026-03-05T08:12:33",
      "datetime_out": "2026-03-05T09:35:10",
      "idle": 82.6
    },
    {
      "device_name": "Truck A-101",
      "people": "Maria Lopez",
      "geofence": "Client Site North",
      "datetime_in": "2026-03-05T10:05:00",
      "datetime_out": null,
      "idle": 0
    }
  ],
  "meta": {
    "total": 47,
    "limit": 50,
    "offset": 0
  }
}

Using `idletime` to filter short visits

With idletime=5, visits under 5 minutes are excluded — useful to filter GPS drift near zone boundaries:

GET /apidev/v1/reports/avl/geofence?startdate=...&enddate=...&idletime=5

Only visits with idle >= 5 are returned.

Errors

Code	HTTP	Description
`BAD_REQUEST`	400	Missing required headers
`VALIDATION_ERROR`	400	Invalid params: missing dates, range > 31 days, malformed ISO date, `limit` > 100, > 500 devices/geofences
`UNAUTHORIZED`	401	Invalid or expired JWT / API Key
`FORBIDDEN`	403	User lacks `APICLI_RPTAVL_GEOCERCA` permission
`RATE_LIMITED`	429	Exceeded 10 req/min
`INTERNAL_ERROR`	500	Unexpected server error

Rate Limits — Sliding window details
Pagination — Standard pagination parameters
Devices API — Get device IDs to filter reports

Overview​

Query Parameters​

Code Examples​

Response Fields​

Example Response​

Using idletime to filter short visits​

Errors​

Related​