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

Detalle de las líneas a la demanda

GET /api/v4/groups/<group_id>/export/on-demand-routes/details devuelve un CSV separado por punto y coma, con una fila por recuento de viajeros, ordenada por fecha y después por passed_at ascendente, además de las filas descritas a continuación para las sesiones de servicio y los kilómetros. start_date y end_date son obligatorios en formato AAAAMMDD y acotan las fechas de servicio, ambos límites incluidos. route_id y teams son opcionales; las restricciones de equipos del lector se aplican igual que en las estadísticas.

Las columnas son, en este orden: date, passed_at, route_id, route_short_name, stop_id, stop_name, vehicle, boarding, alighting, tranche_horaire, route_long_name, stop_lat, stop_lon, service_id, service_start, service_end, service_km. date es la fecha de servicio en formato AAAA-MM-DD; passed_at es un instante ISO 8601 con el desfase de la zona horaria del grupo. Varios recuentos en la misma parada o en el mismo instante siguen siendo filas distintas. tranche_horaire es la hora local de passed_at, límite inferior incluido (08:00-09:00). stop_lat, stop_lon y route_long_name son los de la línea en su configuración actual, y las coordenadas quedan vacías para una parada retirada.

Una sesión de servicio sin ningún recuento tiene su propia fila (parada y hora vacías, 0 en boarding y alighting). service_id, service_start y service_end (hora local, vacía mientras el servicio está abierto) identifican la sesión de cada fila. service_km indica los kilómetros de la sesión para un día local, en la primera fila de esa sesión ese día y vacío en las demás, para que su suma nunca cuente dos veces; una sesión que pasa la medianoche lleva sus kilómetros en cada uno de los dos días, y un día con kilómetros sin recuento tiene su propia fila. Los kilómetros registrados antes de la identificación de las sesiones aparecen en filas con service_id vacío, una por día, línea y dispositivo. Una sesión iniciada antes del periodo solo se lista mediante los recuentos y los kilómetros que tiene dentro de él. Un periodo vacío solo produce la cabecera.

El vehículo es el del servicio de la misma tableta y de la misma línea que contiene el paso: inicio incluido, fin excluido; un servicio sin fin permanece abierto, aunque haya comenzado varios días antes del periodo exportado. En caso de solapamiento, prevalece el servicio iniciado más recientemente. vehicle queda vacío si no hay servicio correspondiente o vehículo conocido; en caso contrario, muestra la matrícula y el número de flota, conservando solo las partes informadas. Una parada retirada de la línea conserva su recuento, con stop_name vacío.

Las sumas de service_km, boarding y alighting por fecha y por línea coinciden con las de export/on-demand-routes con los mismos filtros. Ambas exportaciones requieren los mismos roles de lectura de estadísticas y las funcionalidades ON_DEMAND y DEVICE_EVENT_SOURCING activadas en el grupo. El botón de descarga en Op se entrega por separado.

Exportaciones asíncronas

Para los periodos largos, una exportación puede prepararse en segundo plano en lugar de transmitirse en la respuesta: POST /api/v4/groups/<group_id>/exports crea la tarea y responde 202 con un job_id; GET /api/v4/groups/<group_id>/exports/<job_id> indica su estado (pending, running, succeeded o failed) y, una vez en succeeded, una URL de descarga firmada, renovada en cada lectura. Una tarea solo es visible para quien la solicitó y desaparece al cabo de treinta días, junto con su archivo.

El cuerpo de la solicitud lleva export_type y params. El archivo generado es el mismo CSV que el de la exportación síncrona correspondiente, con los mismos permisos: un rol rechazado por el endpoint síncrono hace que la tarea falle, sin archivo.

export_type params Exportación síncrona equivalente
trip_km start_date, end_date (obligatorios), files, trips_over_days export/trip-km
passenger_counts start_date, end_date (obligatorios) export/passenger-counts
punctuality start_date (obligatorio), end_date, event (arrival o departure), stop_id (lista), gtfs_id, driver_id, route_id export/punctuality

Un parámetro no válido se rechaza con un error 422, sin crear ninguna tarea. Los endpoints síncronos siguen disponibles y sin cambios.

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.