Referencia GTFS¶
Todo parte de aquí. El GTFS describe la oferta teórica de la red (líneas, paradas, trazados, calendarios, horarios) y es lo que da su identidad a las expediciones que la API expone después.
Un grupo conserva varios GTFS¶
Un GTFS no se importa de una vez por todas. Una red cambia de oferta en cada temporada, con cada obra, con cada ajuste del servicio. No se trata de una nueva versión de un GTFS existente: es un nuevo GTFS, con un nuevo identificador. Por tanto, el grupo acumula GTFS distintos, cada uno publicado para su periodo de validez.
La consecuencia práctica es importante: una fecha determina el GTFS vigente. Pedir los horarios de una expedición sin saber a qué GTFS pertenece no tiene sentido en cuanto se sale del día en curso.
| 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 |
GET /api/v4/groups/<group_id>/history/gtfs-active |
Devuelve el GTFS vigente en una fecha pasada |
Para una integración que trabaja con datos históricos, el tercer endpoint es el punto de entrada: evita tener que reconstruir uno mismo la correspondencia entre una fecha y un GTFS.
Consultar y descargar un GTFS sin autenticación¶
La lista de los GTFS de un grupo es pública: muestra también las ofertas futuras y los borradores. Una llamada anónima no recibe ni el autor de la última modificación (mod_user), ni el informe de validación (validation), ni el fallo de una publicación programada (publication_failed): estos campos requieren un rol de lectura en el grupo. Los archivos, por su parte, pueden descargarse sin cuenta en dos casos.
| Endpoint | Acceso anónimo |
|---|---|
GET /api/v4/groups/<group_id>/gtfs |
Siempre: lista los GTFS del grupo, incluidas las ofertas futuras y los borradores |
GET /api/v4/groups/<group_id>/gtfs/pub |
Siempre: es el GTFS vigente, la URL estable que se debe facilitar a un portal de datos abiertos |
GET /api/v4/groups/<group_id>/gtfs/<gtfs_id> |
Si este GTFS ya se ha publicado, o si el operador lo ha compartido para su descarga pública |
Cualquier otro GTFS (borrador, oferta programada, importación nunca compartida) requiere un rol de lectura en el grupo; una llamada anónima recibe 403 NO_ROLE, también para un identificador desconocido. El campo public_download de un GTFS indica si se ha compartido.
Los dos endpoints de archivo responden con una cabecera ETag y una cabecera Last-Modified, y aceptan solicitudes condicionales: devuelva el ETag en If-None-Match (o la fecha en If-Modified-Since) y un archivo sin cambios recibirá un 304 Not Modified vacío, sin reconstruirse. If-None-Match tiene prioridad cuando se envían ambas cabeceras. El ETag también cambia cuando se renombra un equipo del grupo, algo que Last-Modified no refleja.
El ciclo de vida de un GTFS¶
Un GTFS importado no entra en servicio de inmediato. Primero se valida y después se publica; el archivado lo retira del servicio sin destruirlo, de modo que los datos generados mientras estaba activo siguen siendo interpretables.
Por eso un GTFS archivado sigue pudiendo consultarse: las expediciones realizadas hace seis meses se vinculan al GTFS que estaba vigente entonces, y no al de hoy.
| Endpoint | Función |
|---|---|
GET /api/v4/groups/<group_id>/gtfs/<gtfs_id>/validate |
Devuelve el informe de validación de un GTFS |
La validación se apoya en un servicio de control dedicado. Si no responde a tiempo, la llamada devuelve 504 GTFS_VALIDATOR_TIMED_OUT; si no está disponible o responde con un error, 502 GTFS_VALIDATOR_UNAVAILABLE. En ambos casos el GTFS no es la causa: el informe queda pendiente y la llamada puede repetirse más tarde.
Qué contiene la referencia¶
Tres objetos del GTFS aparecen constantemente en la API y se definen en el glosario:
- gtfs: el propio GTFS;
- trips: las expediciones previstas;
- stop-times: sus horarios de paso por las paradas.
Las líneas, paradas y trazados también existen en la referencia, pero la API pública los expone a través de las expediciones y no como colecciones propias: se leen las paradas de una expedición, no el catálogo de paradas.
Siguientes pasos¶
Una vez conocido el GTFS vigente, se puede designar una expedición sin ambigüedad: ese es el objeto de la página Expediciones.