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 |
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.
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.