Reporte de Velocidad

Eventos de exceso de velocidad en tu flota — ubicación, velocidad, duración y datos opcionales de proximidad a radares.

GET/apidev/v1/reports/avl/speed

PermisoAPICLI_RPTAVL_VELOCIDAD

Límite de solicitudes10 req/min (ventana deslizante)

Caché300s (5 min)

Rango máximo31 días

Resumen

Identifica todos los casos en los que un vehículo superó un umbral de velocidad determinado. El reporte tiene dos modos: el modo agrupado (predeterminado) devuelve un registro por cada tramo de exceso de velocidad — de inicio a fin — mientras que detailed=true devuelve un registro por cada posición GPS dentro de los tramos.

Umbral personalizado — speed_threshold define el límite de velocidad para la detección (predeterminado 80 km/h)
Filtrado por duración — duration_min excluye picos breves de velocidad
Modo detallado — detailed=true devuelve cada posición GPS del tramo en lugar del tramo completo
Enriquecimiento con radares — radars=true incluye puntos de interés de radares/cámaras de velocidad cercanos
Subtotales — subtotals=true para resúmenes agregados

Solicitud

Encabezados de la solicitud

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

Parámetros de consulta

Parámetro	Tipo	Requerido	Predeterminado	Descripción
`startdate`	string	Sí	—	Fecha-hora de inicio en ISO 8601 (ej. `2026-03-01T00:00:00`)
`enddate`	string	Sí	—	Fecha-hora de fin en ISO 8601. Rango máximo 31 días
`devices`	string	No	Todos los visibles	IDs de dispositivo separados por coma. Máximo 500
`speed_threshold`	integer	No	`80`	Umbral de velocidad en km/h (`1`–`300`). Se reportan los eventos por encima de este valor
`duration_min`	integer	No	`0`	Duración mínima del exceso de velocidad en minutos. Los eventos más cortos se excluyen
`subtotals`	boolean	No	`false`	Incluye filas de subtotal
`radars`	boolean	No	`false`	Incluye datos de puntos de interés de radares/cámaras de velocidad cercanos. Solo se ven en la respuesta si además pedís `detailed=true`: alimentan el campo `pois`, que el modo agrupado no tiene
`detailed`	boolean	No	`false`	Modo detallado: devuelve un registro por posición GPS en lugar de un registro por tramo de exceso. Cambia los campos de la respuesta — ver Campos de la respuesta
`limit`	integer	No	`25`	Registros por página (`1`–`100`)
`offset`	integer	No	`0`	Registros a omitir

Con subtotals=true cambia el comportamiento de limit

Las filas de subtotal y de total general se agregan después de haber cortado la página, y en este reporte no se vuelven a recortar — así que con subtotals=true la respuesta puede traer más de limit filas.

Las filas de resumen no vienen marcadas en la respuesta. La única forma de reconocerlas es por device_name: un subtotal por móvil dice "<nombre del móvil> (subtotal)" y el total general dice "Total general". Si estás sumando los datos por tu cuenta, filtrá esas filas o vas a contar dos veces.

meta.total cuenta siempre solo las filas de detalle. Para paginar limpio, dejá subtotals apagado y calculá tus propios totales.

Ejemplos de código

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']}")

Campos de la respuesta

La forma de la respuesta depende del parámetro detailed.

Dos formas, nunca mezcladas

Cada fila trae una de las dos formas de abajo — nunca las dos, y nunca un valor vacío en lugar de la otra. Los campos del modo que no pediste no están en el objeto ("datetime_end" in fila da false), no vienen vacíos. Cinco campos son comunes a los dos modos: device_name, person_name, address, datetime y speed.

Si no mandás detailed, obtenés el modo agrupado.

Modo agrupado (predeterminado)

Un registro por cada tramo de exceso de velocidad — el evento completo, desde que el vehículo supera el umbral hasta que vuelve a estar por debajo:

Campo	Tipo	Descripción
`device_name`	string	Nombre visible del vehículo/dispositivo
`person_name`	string	Conductor asignado al momento del evento (cadena vacía si no hay)
`address`	string	Dirección geocodificada inversa donde comienza el tramo
`datetime`	string \| null	Marca de tiempo de inicio del tramo
`speed`	number	Velocidad al inicio del tramo (km/h)
`datetime_end`	string \| null	Marca de tiempo de fin del tramo
`address_end`	string	Dirección donde termina el tramo
`speed_end`	number	Velocidad al final del tramo (km/h)
`duration_min`	number	Duración del tramo en minutos. No confundir con el parámetro de consulta `duration_min`, que es el filtro de duración mínima

{
  "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": 91,
      "duration_min": 2
    }
  ],
  "meta": {
    "total": 23,
    "limit": 50,
    "offset": 0
  }
}

Modo detallado (`detailed=true`)

Un registro por cada posición GPS dentro de los tramos de exceso — muchas más filas que el modo agrupado:

Campo	Tipo	Descripción
`device_name`	string	Nombre visible del vehículo/dispositivo
`person_name`	string	Conductor asignado
`address`	string	Dirección de la posición
`datetime`	string \| null	Marca de tiempo de la posición
`speed`	number	Velocidad en esa posición (km/h)
`step`	string	Posición dentro del tramo: `COMIENZA` / `continua` / `FINALIZA`
`pois`	string	Puntos de interés de radares/cámaras de velocidad cercanos (cuando `radars=true`). Cadena vacía cuando está deshabilitado o no se encontraron puntos de interés

{
  "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": 112,
    "limit": 50,
    "offset": 0
  }
}

Errores

Código	HTTP	Descripción
`INVALID_DATE_RANGE`	400	El rango de fechas supera el máximo de 31 días, el fin es anterior al inicio, o fechas no ISO
`VALIDATION_ERROR`	400	Parámetros inválidos: faltan fechas, `speed_threshold` fuera del rango 1–300, `limit` > 100
`UNAUTHORIZED`	401	tenant / Authorization / X-API-Key faltante, inválido o expirado
`FORBIDDEN`	403	El usuario carece del permiso `APICLI_RPTAVL_VELOCIDAD`
`RATE_LIMITED`	429	Se superaron las 10 req/min
`INTERNAL_ERROR`	500	Error inesperado del servidor

Reporte de Viajes — Registros de viajes individuales con datos de velocidad
Reporte de Kilómetros — Agregados de distancia y consumo
Límites de solicitudes — Detalles de la ventana deslizante
Paginación — Parámetros de paginación estándar

Resumen​

Solicitud​

Encabezados de la solicitud​

Parámetros de consulta​

Ejemplos de código​

Campos de la respuesta​

Modo agrupado (predeterminado)​

Modo detallado (detailed=true)​

Errores​

Relacionado​