Skip to main content

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:

HeaderRequiredDescription
AuthorizationYesBearer token obtained from the Login endpoint. Format: Bearer <token>
X-API-KeyYesCompany integration key provided during onboarding. Format: gtk_xxx...
tenantYesYour assigned tenant domain (default: geotareas.com) — always send your assigned tenant
Content-TypeConditionalapplication/json — required for POST and PUT requests

Query Parameters​

ParameterTypeRequiredDefaultDescription
startdatestringYes—ISO 8601 start date-time (e.g. 2026-03-01T00:00:00)
enddatestringYes—ISO 8601 end date-time. Max range 31 days
devicesstringNoAll visibleComma-separated device IDs. Max 500
speed_thresholdintegerNo80Speed threshold in km/h (1–300). Events above this are reported
duration_minintegerNo0Minimum overspeed duration in minutes. Shorter events are excluded
subtotalsbooleanNofalseInclude subtotal rows
radarsbooleanNofalseInclude nearby radar/speed-camera POI data
detailedbooleanNofalseReturn one record per GPS position instead of one per overspeed segment
limitintegerNo25Records per page (1–100)
offsetintegerNo0Records to skip

Code Examples​

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"

Response Fields​

The response shape depends on the detailed parameter.

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:

FieldTypeDescription
device_namestringDisplay name of the vehicle/device
person_namestringName of the assigned driver at the time of the event. Empty string if none
addressstringReverse-geocoded address where the segment starts
datetimestring | nullTimestamp when the segment started
speednumberSpeed at the start of the segment (km/h)
datetime_endstring | nullTimestamp when the segment ended
address_endstringReverse-geocoded address where the segment ends
speed_endnumberSpeed at the end of the segment (km/h)
duration_minnumberDuration of the segment in minutes

Detailed mode (detailed=true)​

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

FieldTypeDescription
device_namestringDisplay name of the vehicle/device
person_namestringName of the assigned driver at the time of the event
addressstringReverse-geocoded address of the position
datetimestring | nullTimestamp of the position
speednumberSpeed at that position (km/h)
stepstringPosition within the segment: COMIENZA (start), continua (in progress), FINALIZA (end)
poisstringNearby 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​

CodeHTTPDescription
INVALID_DATE_RANGE400Date range exceeds the 31-day maximum, end before start, or non-ISO dates
VALIDATION_ERROR400Invalid params: missing dates, speed_threshold outside 1–300, limit > 100
UNAUTHORIZED401Missing, invalid, or expired tenant / Authorization / X-API-Key
FORBIDDEN403User lacks APICLI_RPTAVL_VELOCIDAD permission
RATE_LIMITED429Exceeded 10 req/min
INTERNAL_ERROR500Unexpected server error