Reporte de Kilómetros

Distancia recorrida, consumo de combustible y métricas de costo de tu flota durante un período determinado.

GET/apidev/v1/reports/avl/kilometers

PermisoAPICLI_RPTAVL_KILOMETROS

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

Caché300s (5 min)

Rango máximo31 días

Resumen

Proporciona datos de distancia y consumo para cada vehículo de tu flota. Úsalo para auditar el kilometraje, estimar costos de combustible y hacer seguimiento de las emisiones de CO₂.

Desglose diario — perday=true devuelve una fila por vehículo por día
Agrupación por conductor — perperson=true segmenta los resultados por el conductor asignado
Subdivisión geográfica — groupbygeo divide los totales por estado, ciudad o barrio
Subtotales — subtotals=true incluye filas de resumen

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 desde `startdate`
`devices`	string	No	Todos los visibles	IDs de dispositivo separados por coma. Máximo 500
`limit`	integer	No	`25`	Registros por página (`1`–`100`)
`offset`	integer	No	`0`	Registros a omitir
`perday`	boolean	No	`false`	Agrupa los resultados por día
`perperson`	boolean	No	`false`	Agrupa los resultados por conductor asignado
`subtotals`	boolean	No	`false`	Incluye filas de subtotal
`groupbygeo`	enum	No	—	Subdivide por área: `state`, `city` o `neighbourhood`

Visibilidad de dispositivos

Cuando se omite devices, el reporte incluye todos los dispositivos visibles para el usuario autenticado según su alcance de permisos.

Ejemplos de código

cURL
JavaScript
Python

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

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

const { data, meta } = await response.json();
console.log(`${data.length} rows of ${meta.total}`);

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

result = response.json()
for row in result["data"]:
    print(f"{row['device_name']}: {row['kms']} km — {row['fuel']} L")

Campos de la respuesta

Campo	Tipo	Descripción
`device_name`	string	Nombre visible del vehículo/dispositivo
`person_name`	string	Nombre del conductor asignado (solo se completa con `perperson=true`)
`datetime`	string \| null	Fecha del registro (`YYYY-MM-DD`, solo se completa con `perday=true`)
`kms`	number	Total de kilómetros recorridos
`fuel`	number	Combustible consumido estimado (litros)
`cost`	number	Costo de combustible estimado (moneda según configuración del vehículo)
`co2`	number	Emisiones de CO₂ estimadas (kg)
`temperature`	number	Lectura promedio del sensor de temperatura 1. `0` si el vehículo no tiene sensor
`state`	string	Nombre del estado (solo se completa con `groupbygeo`)
`city`	string	Nombre de la ciudad (solo se completa con `groupbygeo=city` o `neighbourhood`)
`neighbourhood`	string	Nombre del barrio (solo se completa con `groupbygeo=neighbourhood`)

Valores de combustible y costo

fuel, cost y co2 se calculan usando la tasa de consumo de combustible y el precio de combustible configurados en los ajustes de cada vehículo. Si no están configurados, estos campos devuelven 0.

Ejemplo de respuesta

{
  "success": true,
  "data": [
    {
      "device_name": "Truck A-101",
      "person_name": "",
      "datetime": "2026-03-01",
      "kms": 267.7,
      "fuel": 32.12,
      "cost": 48.18,
      "co2": 83.54,
      "temperature": 22.3,
      "state": "",
      "city": "",
      "neighbourhood": ""
    },
    {
      "device_name": "Van B-205",
      "person_name": "",
      "datetime": "2026-03-01",
      "kms": 142.3,
      "fuel": 11.38,
      "cost": 17.07,
      "co2": 29.57,
      "temperature": 4.1,
      "state": "",
      "city": "",
      "neighbourhood": ""
    }
  ],
  "meta": {
    "total": 84,
    "limit": 50,
    "offset": 0
  }
}

Con `perperson=true`

Cuando la agrupación por conductor está habilitada, person_name se completa y pueden aparecer varias filas para el mismo dispositivo si los conductores cambiaron durante el período:

{
  "device_name": "Truck A-101",
  "person_name": "Carlos Martinez",
  "datetime": "2026-03-01",
  "kms": 180.5,
  "fuel": 21.66,
  "cost": 32.49,
  "co2": 56.32,
  "temperature": 22.3,
  "state": "",
  "city": "",
  "neighbourhood": ""
}

Con `groupbygeo=state`

La subdivisión geográfica completa el campo geo correspondiente:

{
  "device_name": "Truck A-101",
  "person_name": "",
  "datetime": null,
  "kms": 180.5,
  "fuel": 21.66,
  "cost": 32.49,
  "co2": 56.32,
  "temperature": 0,
  "state": "Montevideo",
  "city": "",
  "neighbourhood": ""
}

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, `limit` > 100, > 500 dispositivos
`UNAUTHORIZED`	401	tenant / Authorization / X-API-Key faltante, inválido o expirado
`FORBIDDEN`	403	El usuario carece del permiso `APICLI_RPTAVL_KILOMETROS`
`RATE_LIMITED`	429	Se superaron las 10 req/min
`INTERNAL_ERROR`	500	Error inesperado del servidor

Límites de solicitudes — Detalles de la ventana deslizante
Paginación — Parámetros de paginación estándar
API de Dispositivos — Obtené IDs de dispositivo para filtrar reportes

Resumen​

Solicitud​

Encabezados de la solicitud​

Parámetros de consulta​

Ejemplos de código​

Campos de la respuesta​

Ejemplo de respuesta​

Con perperson=true​

Con groupbygeo=state​

Errores​

Relacionado​