Saltar a contenido

Red

La referencia teórica: lo que la red tiene previsto hacer. Procede del GTFS importado y solo cambia al publicarse un nuevo GTFS.

gtfs

GTFS — el conjunto de datos que describe la oferta teórica de la red: líneas, paradas, trazados, calendarios y horarios. Formato estándar del sector, se importa en el grupo y después se publica para convertirse en la referencia vigente.

Identificador <gtfs_id>. Un grupo conserva varios GTFS: el que está en servicio, los anteriores y los futuros. No son versiones de un mismo GTFS: cuando la oferta cambia, se importa un nuevo GTFS, con un nuevo identificador. Cada uno se publica para un periodo de validez, de modo que una fecha determinada define el GTFS vigente. Las expediciones, los horarios en paradas y las frecuencias pertenecen a un GTFS concreto; por eso una expedición se designa por su identificador y su gtfs_id.

Endpoint Función
GET /api/v4/groups/<group_id>/gtfs Lista los GTFS del grupo
GET /api/v4/groups/<group_id>/gtfs/<gtfs_id> Descarga el archivo zip de un GTFS (de forma anónima si se ha publicado o compartido)
GET /api/v4/groups/<group_id>/gtfs/<gtfs_id>/validate Devuelve el informe de validación

El ciclo de vida de un GTFS se refleja en estas tres llamadas: un GTFS importado permanece inactivo hasta su publicación, y el archivado lo retira del servicio sin destruirlo.

Endpoint Función
POST /api/v4/groups/<group_id>/gtfs Importa un nuevo GTFS
POST /api/v4/groups/<group_id>/gtfs/<gtfs_id>/publish Pone el GTFS en servicio
POST /api/v4/groups/<group_id>/gtfs/<gtfs_id>/archive Retira el GTFS del servicio

trips

Expedición — un trayecto previsto en una línea, con su recorrido y sus horarios de paso. Es el objeto central de la explotación: las expediciones se planifican, se asignan, se siguen y se mide su realización.

Identificador <trip_id>, que procede del GTFS. Una expedición por sí sola no basta para designar un trayecto real: se necesita el triplete identificador de expedición, fecha de servicio y gtfs_id, ya que un identificador de expedición solo es único dentro de su GTFS y la expedición se repite cada día de circulación. Los tres componentes forman una clave única: el triplete designa una y solo una ejecución de la expedición.

Endpoint Función
GET /api/v4/groups/<group_id>/trips Lista las expediciones de un periodo
GET /api/v4/groups/<group_id>/trips/<trip_id> Describe una expedición
GET /api/v4/groups/<group_id>/export/trips Exporta las expediciones realizadas en formato CSV

stop-times

Horario en paradas — las horas de paso previstas de una expedición en cada una de las paradas que atiende, en orden. Es lo que permite decir que un vehículo va con adelanto o con retraso: la diferencia se mide siempre respecto al horario teórico de la parada correspondiente.

Sin identificador propio: un horario se designa por su expedición y la posición de la parada en la secuencia.

Endpoint Función
GET /api/v4/groups/<group_id>/stop-times Devuelve los horarios previstos en las paradas

Los horarios observados realmente se conservan aparte y se describen en la entrada history.

frequencies

Frecuencia — una forma de describir la oferta en la que una expedición no se define por sus horarios exactos, sino por un intervalo de paso en una franja horaria, por ejemplo un autobús cada diez minutos de 7:00 a 9:00. Noción estándar del GTFS, utilizada en las líneas de alta frecuencia.

Sin identificador propio: una frecuencia pertenece a una expedición y a una franja horaria.

Estos datos se sirven a la aplicación Pysae Driver y no se publican en la especificación pública.

Endpoint Función
GET /api/v4/groups/<group_id>/frequencies Devuelve las frecuencias declaradas

planning

Planificación — la asignación prevista de los medios a las expediciones: qué conductor y qué vehículo realizan qué expedición y en qué fecha. Es el puente entre la referencia teórica y los medios reales del grupo.

Sin identificador propio: una línea de planificación se designa por su expedición y su fecha. Hace referencia a un conductor, un vehículo y, en su caso, un bloque: la sucesión de expediciones encadenadas por un mismo vehículo.

Endpoint Función
GET /api/v4/groups/<group_id>/planning Devuelve la asignación prevista en un periodo
PUT /api/v4/groups/<group_id>/planning Registra la asignación prevista

Una importación que hace referencia a un conductor (staff_number) o a un vehículo (license_plate) que no existe en el grupo se rechaza por completo: la respuesta 422 enumera, en detail.missing, los conductores y vehículos no encontrados. Con force=true, las demás líneas se importan de todos modos; las que hacen referencia a una entidad inexistente se descartan, y la respuesta enumera tanto las asignaciones registradas (inserted) como lo que no se ha encontrado (missing). La importación se sigue rechazando si no queda ninguna línea.

La planificación es una previsión. Lo que se ha realizado realmente se consulta en el servicio de conducción, descrito en la entrada duties.