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.punctualityytrip-trackingtoleran tambiénAAAA-MM-DD, perotrips,trip-kmypassenger-countslo 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.