Saltar a contenido

Estadísticas y exportaciones

Para analizar el servicio en periodos largos, no se recorren los endpoints unitarios: la API ofrece salidas masivas, en dos formas.

Dos formas, dos usos

Forma Ruta Lo que devuelve Para qué
Agregado /stats/<dominio> Valores ya calculados sobre el periodo Cuadro de mando, indicador de seguimiento
Exportación /export/<dominio> El detalle fila a fila Almacén de datos, reprocesamiento

La elección depende de la necesidad: un agregado evita recalcular lo que la API ya sabe hacer, una exportación proporciona la materia prima para análisis que la API no prevé.

Las ocho exportaciones

Estos ocho endpoints constituyen la categoría datahub, prevista para alimentar un almacén de datos.

Exportación Parámetros esperados
export/trips date (obligatorio)
export/trip-km start_date, end_date (obligatorios)
export/passenger-counts start_date, end_date (obligatorios)
export/punctuality start_date (obligatorio), end_date y filtros opcionales (event: arrival o departure, stop_id, gtfs_id, driver_id, route_id)
export/trip-tracking start_date, end_date (obligatorios)
export/drivers archived (opcional)
export/vehicles statuses (opcional)
export/alerts ninguno

Tres puntos que conviene leer con atención antes de escribir un cliente:

  • Las exportaciones no comparten la misma firma. Algunas acotan un periodo, solo una recibe una fecha única y tres no reciben ninguna. No existe una llamada genérica que pueda escribirse una vez para las ocho.
  • Escriba las fechas en el formato compacto AAAAMMDD. Es el único que aceptan los cinco endpoints con fecha. punctuality y trip-tracking toleran también AAAA-MM-DD, pero trips, trip-km y passenger-counts lo rechazan con un error de validación.
  • El perímetro sigue los permisos de la clave. Una clave restringida a determinados equipos exporta menos filas de las esperadas, sin que nada lo indique en la respuesta.

Los ocho endpoints devuelven CSV. No obstante, el spec declara application/json para export/trips: se trata de un error de declaración, el contenido servido es efectivamente CSV.

Kilómetros por expedición

El recuento único que se describe a continuación se activa progresivamente por red, tras informar a los usuarios de las exportaciones. Mientras no esté activado para su red, los kilómetros teóricos y los desvíos se siguen contando en cada realización como hasta ahora.

Cuando varios dispositivos han realizado la misma expedición el mismo día, la exportación conserva todas las filas y sus kilómetros realizados. Los kilómetros teóricos se cuentan una sola vez, en la fila con más kilómetros realizados. En caso de empate, se retiene la realización que comenzó antes; un inicio conocido tiene prioridad sobre un inicio ausente, y después el identificador del registro deshace los empates restantes de forma estable.

Las filas secundarias llevan theoretical_commercial_km a cero. La diferencia deviated_km y el total theoretical_commercial_km_with_deviation siguen la misma regla; un valor no medido queda vacío. Las estadísticas por día y por línea cuentan también únicamente el desvío de la realización principal. Los kilómetros realizados y el denominador nominal de la tasa de realización no cambian.

Esta regla se aplica también a las exportaciones históricas: sus totales teóricos pueden, por tanto, disminuir. En Excel, Power BI u otra integración, proteja las divisiones realizadas fila a fila frente a un teórico nulo. El formato y el número de filas del CSV se conservan.

En la exportación de puntualidad, los pasos de una expedición se ordenan por instante y después por número de parada, con la llegada antes de la salida cuando ambos eventos comparten el mismo instante. Las expediciones empatadas según las claves de salida se desempatan por los identificadores de GTFS, expedición y fecha de servicio. Con los mismos parámetros y datos, este orden hace que el CSV sea reproducible, incluida la columna de distancia.

Los agregados

Los mismos dominios existen en versión calculada, bajo /stats/. Acotan el periodo mediante start_date y end_date en formato AAAAMMDD, salvo stats/punctuality, que recibe from y to como timestamp Unix expresado en segundos. Una fecha AAAAMMDD pasada a from o to se rechaza ahí con un error 422, al igual que cualquier valor anterior al 1 de enero de 2015.

Endpoint Función
GET /api/v4/groups/<group_id>/stats/punctuality Puntualidad agregada sobre el periodo
GET /api/v4/groups/<group_id>/stats/trip-km Kilómetros recorridos
GET /api/v4/groups/<group_id>/stats/passenger-counts Afluencia de viajeros
GET /api/v4/groups/<group_id>/stats/vehicles-used Vehículos utilizados

Consultar el pasado

Una exportación abarca un periodo cerrado. Para reconstruir en detalle una jornada ya transcurrida —eventos transmitidos, pasos observados, GTFS vigente en ese momento— hay que consultar el historial.

El recordatorio de la página Referencial GTFS se aplica aquí plenamente: los datos de hace seis meses se interpretan según el GTFS vigente en esa fecha, no según el actual.

Buenas prácticas

  • Divida los periodos largos. Una exportación de un año entero produce una respuesta voluminosa y una solicitud larga; encadenar tramos mensuales es más seguro y permite retomar en caso de fallo.
  • No fije un tiempo de espera corto. Estas respuestas se transmiten de forma continua y una exportación amplia tarda en comenzar.
  • Repetir una exportación no tiene efectos secundarios. Estos endpoints son de solo lectura: en caso de duda sobre un tramo, volver a solicitarlo solo cuesta la transferencia.

Los ejemplos de código correspondientes, en el lenguaje seleccionado en la cabecera, se encuentran en la página Ejemplos de recopilación.