Speed Report

Overspeed events across your fleet — location, speed, duration, and optional radar proximity data.

GET/apidev/v1/reports/avl/speed

PermissionAPICLI_RPTAVL_VELOCIDAD

Rate Limit10 req/min (sliding window)

Cache300s (5 min)

Max Range31 days

Overview

Identifies all instances where a vehicle exceeded a given speed threshold. The report has two modes:

Grouped mode (default) — one record per overspeed segment: from the moment the vehicle crosses the threshold until it drops back below it, with start/end time, address, and speed
Detailed mode (detailed=true) — one record per GPS position inside each segment, flagged as the start, continuation, or end of the segment

Additional options:

Custom threshold — speed_threshold defines the speed limit for detection (default 80 km/h)
Duration filtering — duration_min excludes brief speed spikes
Radar enrichment — radars=true includes nearby radar/speed-camera POIs
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 (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
`speed_threshold`	integer	No	`80`	Speed threshold in km/h (`1`–`300`). Events above this are reported
`duration_min`	integer	No	`0`	Minimum overspeed duration in minutes. Shorter events are excluded
`subtotals`	boolean	No	`false`	Include subtotal rows
`radars`	boolean	No	`false`	Include nearby radar/speed-camera POI data. Only surfaces in the response when combined with `detailed=true` — it fills the `pois` field, which grouped mode does not have
`detailed`	boolean	No	`false`	Return one record per GPS position instead of one per overspeed segment. Changes the response fields — see Response Fields
`limit`	integer	No	`25`	Records per page (`1`–`100`)
`offset`	integer	No	`0`	Records to skip

subtotals=true changes how limit behaves

The subtotal and grand-total rows are appended after the page has been cut, and on this report they are not trimmed back — so with subtotals=true the response can return more than limit rows.

Summary rows are not flagged in the payload. You can only recognise them by device_name: a per-device subtotal reads "<device name> (subtotal)" and the grand total reads "Total general". If you are aggregating the data yourself, filter those rows out or you will double-count.

meta.total always counts detail rows only. For a clean paginated read, leave subtotals off and compute your own totals.

Code Examples

cURL
JavaScript
Python

curl -s "https://$TENANT/apidev/v1/reports/avl/speed?startdate=2026-03-01T00:00:00&enddate=2026-03-15T23:59:59&limit=50&speed_threshold=90" \
  -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",
  speed_threshold: "90",
});

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

const { data, meta } = await response.json();
for (const event of data) {
  console.log(`${event.device_name}: ${event.speed} km/h at ${event.address}`);
}

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

result = response.json()
for event in result["data"]:
    print(f"{event['device_name']}: {event['speed']} km/h — {event['address']}")

Response Fields

The response shape depends on the detailed parameter.

Two shapes, never mixed

Each row carries one of the two shapes below — never both, and never a blank placeholder for the other one. The fields of the mode you did not ask for are absent from the object ("datetime_end" in row is false), not present with an empty value. Five fields are common to both modes: device_name, person_name, address, datetime and speed.

If you omit detailed, you get grouped mode.

Grouped mode (default)

One record per overspeed segment — the full event from the moment the vehicle crosses the threshold until it drops back below it:

Field	Type	Description
`device_name`	string	Display name of the vehicle/device
`person_name`	string	Name of the assigned driver at the time of the event. Empty string if none
`address`	string	Reverse-geocoded address where the segment starts
`datetime`	string \| null	Timestamp when the segment started
`speed`	number	Speed at the start of the segment (km/h)
`datetime_end`	string \| null	Timestamp when the segment ended
`address_end`	string	Reverse-geocoded address where the segment ends
`speed_end`	number	Speed at the end of the segment (km/h)
`duration_min`	number	Duration of the segment in minutes. Not to be confused with the `duration_min` query parameter, which is the minimum-duration filter

Detailed mode (`detailed=true`)

One record per GPS position inside the overspeed segments (many more rows):

Field	Type	Description
`device_name`	string	Display name of the vehicle/device
`person_name`	string	Name of the assigned driver at the time of the event
`address`	string	Reverse-geocoded address of the position
`datetime`	string \| null	Timestamp of the position
`speed`	number	Speed at that position (km/h)
`step`	string	Position within the segment: `COMIENZA` (start), `continua` (in progress), `FINALIZA` (end)
`pois`	string	Nearby radar/speed-camera POIs (when `radars=true`). Empty string when disabled or no POIs found

Example Response — grouped mode (default)

{
  "success": true,
  "data": [
    {
      "device_name": "Sedan C-310",
      "person_name": "Ana Lopez",
      "address": "Ruta 1 km 45, San Jose",
      "datetime": "2026-03-07T14:22:15",
      "speed": 96,
      "datetime_end": "2026-03-07T14:43:01",
      "address_end": "Ruta 1 km 78, Colonia",
      "speed_end": 88,
      "duration_min": 21
    },
    {
      "device_name": "Truck A-101",
      "person_name": "Carlos Martinez",
      "address": "Av. Italia 2800, Montevideo",
      "datetime": "2026-03-07T16:10:33",
      "speed": 95,
      "datetime_end": "2026-03-07T16:12:05",
      "address_end": "Av. Italia 3400, Montevideo",
      "speed_end": 82,
      "duration_min": 2
    }
  ],
  "meta": {
    "total": 23,
    "limit": 50,
    "offset": 0
  }
}

Example Response — detailed mode (`detailed=true`)

{
  "success": true,
  "data": [
    {
      "device_name": "Sedan C-310",
      "person_name": "Ana Lopez",
      "address": "Ruta 1 km 45, San Jose",
      "datetime": "2026-03-07T14:22:15",
      "speed": 96,
      "step": "COMIENZA",
      "pois": "Radar Km 44 (320m)"
    },
    {
      "device_name": "Sedan C-310",
      "person_name": "Ana Lopez",
      "address": "Ruta 1 km 52, San Jose",
      "datetime": "2026-03-07T14:27:40",
      "speed": 102,
      "step": "continua",
      "pois": ""
    },
    {
      "device_name": "Sedan C-310",
      "person_name": "Ana Lopez",
      "address": "Ruta 1 km 78, Colonia",
      "datetime": "2026-03-07T14:43:01",
      "speed": 88,
      "step": "FINALIZA",
      "pois": ""
    }
  ],
  "meta": {
    "total": 156,
    "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, `speed_threshold` outside 1–300, `limit` > 100
`UNAUTHORIZED`	401	Missing, invalid, or expired tenant / Authorization / X-API-Key
`FORBIDDEN`	403	User lacks `APICLI_RPTAVL_VELOCIDAD` permission
`RATE_LIMITED`	429	Exceeded 10 req/min
`INTERNAL_ERROR`	500	Unexpected server error

Trips Report — Individual trip records with speed data
Kilometers Report — Distance and consumption aggregates
Rate Limits — Sliding window details
Pagination — Standard pagination parameters

Overview​

Request​

Request Headers​

Query Parameters​

Code Examples​

Response Fields​

Grouped mode (default)​

Detailed mode (detailed=true)​

Example Response — grouped mode (default)​

Example Response — detailed mode (detailed=true)​

Errors​

Related​