Saltar a contenido

Estaciones ferroviarias

La API publica el referencial de estaciones de viajeros de la SNCF: 2782 estaciones, cada una con su código UIC, su posición y su adscripción administrativa. Es la única parte de la API que no pertenece a nadie: sin grupo, sin clave, sin derechos.

Qué distingue a este endpoint

Resto de la API Estaciones ferroviarias
Ámbito /groups/<group_id>/… ningún grupo
Autenticación clave de API o sesión obligatoria ninguna
Origen de los datos el GTFS de su red y la información de campo el conjunto de datos abierto de la SNCF gares-de-voyageurs
Cambia cuando de forma continua, durante el servicio cuando la SNCF revisa su conjunto de datos y el referencial se recarga manualmente

La consecuencia que conviene tener presente: aquí nada es en tiempo real y nada es propio de su red. Es un índice, pensado para leerse antes que todo lo demás; típicamente, para designar mediante su código UIC la estación a la que corresponde una parada de su red.

Los dos endpoints

Endpoint Función
GET /api/v4/rail-stations Busca en el referencial por nombre o por proximidad
GET /api/v4/rail-stations/<uic> Lee una estación a partir de uno de sus códigos UIC

Buscar por nombre

q se busca en cualquier parte del nombre de la estación, sin tener en cuenta mayúsculas, acentos ni separadores. chateauroux encuentra Châteauroux, y saint germain encuentra Saint-Germain-en-Laye Bel-Air – Fourqueux. No tiene que normalizar nada por su parte.

curl --fail --location --get \
  --data-urlencode "q=Châteauroux" \
  "https://api.pysae.com/api/v4/rail-stations"

La respuesta incluye la página y su total, como cualquier endpoint paginado de la API:

{
  "items": [
    {
      "uic": ["87597005"],
      "name": "Châteauroux",
      "short_label": "CTX",
      "segments_drg": ["A"],
      "lat": 46.809737,
      "lon": 1.699536,
      "insee_code": "36044",
      "source_ref": "0054eed7-a134-4fca-b217-d65e4d2ea153"
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 50
}

Buscar por proximidad

near=<latitude>,<longitude> ordena los resultados por distancia creciente y añade distance_meters a cada uno. radius, en metros, limita la búsqueda; su valor predeterminado es 10 km y se ignora si near no está presente.

GET /api/v4/rail-stations?near=48.880185,2.355151&radius=3000 devuelve las estaciones situadas a menos de 3 km de Paris Gare du Nord, empezando por la más cercana.

Ambos filtros se combinan: q y near juntos devuelven las estaciones cuyo nombre coincide, dentro del radio, ordenadas por distancia.

Una estación, varios códigos UIC

uic es una lista y no un valor único: es el aspecto que sorprende al integrar. La SNCF asigna varios códigos a una misma estación cuando la sirven varias redes: Paris Gare du Nord tiene tres y Avignon TGV, dos. Las consecuencias:

  • Cualquiera de los códigos de una estación la resuelve. GET /api/v4/rail-stations/87271007 y GET /api/v4/rail-stations/87271031 devuelven ambos Paris Gare du Nord.
  • Un código pertenece a una sola estación. Ningún código UIC se comparte, por lo que resolver uno nunca es ambiguo.
  • segments_drg es una lista por la misma razón. El segmento de afluencia DRG (A el más concurrido, C el menos) se da por código, así que una estación con varios códigos puede tener varios segmentos.

Almacenar un único código por su parte basta para designar una estación, siempre que lea uic como una lista al comparar.

Vincular una parada de su red a una estación

La vinculación convierte el índice anterior en un dato de servicio: designa, para una parada de su GTFS, la estación cuyas salidas muestra, y delimita las estaciones cuyos datos ferroviarios se ingieren para su red. A diferencia del referencial, esta parte es propia de cada grupo y depende de la funcionalidad de pago rail_data: sin ella, los endpoints responden 403 con el código LOCKED_FEATURE.

GET /api/v4/groups/<group_id>/rail/station-links lista las vinculaciones del grupo. Cada vínculo incluye la parada (stop_id, con stop_name como etiqueta), la estación (uic) y un indicador is_orphan: true cuando la parada no existe —o ya no existe— en el GTFS publicado actualmente por el grupo. Un vínculo huérfano nunca se rechaza ni se elimina de oficio: sus paradas se reimportan con cada GTFS, y el vínculo debe sobrevivir a una reimportación que haga desaparecer momentáneamente su parada. Le corresponde a usted mostrar el indicador y corregir o retirar el vínculo.

Cada vínculo incluye también un ingestion_status, que indica en qué punto están los datos ferroviarios de la estación: ready cuando sus salidas se pueden consultar, pending mientras la estación se está ingiriendo, not_found cuando ningún tren del feed nacional actual la sirve. Vincular una estación que todavía no está en el almacén ferroviario responde de inmediato con pending y prepara sus datos de forma asíncrona, normalmente en cuestión de minutos; vuelva a listar los vínculos hasta que pase a ready y, mientras tanto, muestre «preparación en curso» en lugar de un panel de salidas vacío. not_found no es un error: el vínculo se conserva, y la actualización diaria lo reevalúa con cada nuevo feed de la SNCF.

Leer el panel de salidas de una estación vinculada

Para esto sirve la vinculación: GET /api/v4/groups/<group_id>/rail/departures?stop_id=<stop_id> devuelve los trenes que salen de las estaciones vinculadas a esa parada de su red, con horarios teóricos y tiempo real combinados. Misma funcionalidad de pago rail_data que las vinculaciones: sin ella, 403 LOCKED_FEATURE.

La parada se designa por su stop_id en su GTFS, no por un código UIC. Una parada vinculada a varias estaciones devuelve las salidas de todas ellas en una sola lista.

La ventana horaria

from y to son instantes absolutos, en ISO 8601 o en segundos epoch, como en el resto de la API. Ambos límites están incluidos.

Lo que usted envía Ventana aplicada
nada ahora → ahora + 1 h
solo from from → from + 1 h
solo to to - 1 h → to
ambos tal cual, 24 h como máximo

Una ventana invertida o de más de 24 h se rechaza con un 400 INVALID_RAIL_DEPARTURES_WINDOW: más allá, lo que pide es un catálogo de horarios, no un panel de salidas.

La respuesta

Una lista ordenada por scheduled_departure creciente, es decir, el horario teórico, sobre el que filtra la ventana, para que el orden no cambie cuando evolucionan las estimaciones.

Campo Función
scheduled_departure El horario teórico. Siempre presente
estimated_departure El horario estimado por el tiempo real, null si no lo hay
delay_seconds La diferencia con signo entre ambos, negativa para un tren adelantado
status scheduled, on_time, delayed, early, canceled, skipped, added
destination Lo que hay que mostrar: stop_headsign, si no trip_headsign, si no el nombre de la última parada del tren
route_type El modo, route_type de GTFS
platform La vía, si la fuente la publica
disruptions Las alertas en tiempo real que afectan a este tren, a su línea, a la estación o a toda la red
service_date El día de servicio (YYYYMMDD), que no coincide con el día natural para un tren que sale después de medianoche

Tres trampas que conviene conocer:

  • Solo se listan los trenes en los que se puede subir. Un tren que termina su expedición en la estación, o que solo para en ella para el descenso de viajeros, no es una salida: figura en el panel de llegadas.
  • status: scheduled significa «sin tiempo real», no «puntual». Cuando ninguna entidad en tiempo real cubre el tren, el panel se sirve solo con sus horarios teóricos: estimated_departure y delay_seconds quedan en null y disruptions está vacío. La ausencia de tiempo real degrada la visualización, nunca hace fallar la llamada, y se produce tren a tren, no panel a panel.
  • Ningún filtro por modo. Se devuelven todos los modos que sirven la estación, incluidos los autocares de sustitución Car TER (route_type 3): forman parte del servicio que el viajero debe ver. Filtre en el cliente por route_type si solo quiere los trenes.

platform es opcional de principio a fin: procede del platform_code del GTFS de la fuente, que el feed nacional de la SNCF no publica. Cuente con null en los datos de la SNCF y no lo convierta en una columna obligatoria de su visualización.

Una parada no vinculada a ninguna estación responde 200 con una lista vacía: es un estado de configuración, no un error. Lo mismo ocurre con una estación cuyos datos aún no se han ingerido: consulte ingestion_status en la vinculación para distinguir «en preparación» de «ningún tren».

Leer el panel de llegadas de una estación vinculada

GET /api/v4/groups/<group_id>/rail/arrivals?stop_id=<stop_id> es el reflejo del panel de salidas: los trenes que llegan a las estaciones vinculadas a esa parada, con la misma funcionalidad rail_data, la misma ventana, las mismas fuentes y el mismo tiempo real. Solo cambia lo que depende del sentido.

En el panel de salidas En el panel de llegadas
scheduled_departure, estimated_departure scheduled_arrival, estimated_arrival
destination origin: el nombre de la primera parada de la expedición del tren
ordenado por scheduled_departure ordenado por scheduled_arrival
se excluye un tren que termina su expedición en la estación se lista un tren que termina su expedición en la estación
se lista un tren que empieza su expedición en la estación se excluye un tren que empieza su expedición en la estación

scheduled_departure se sigue devolviendo en una llegada cuando el tren vuelve a salir de la estación, y es null en su terminal. delay_seconds es el retraso de la llegada, y disruptions, las alertas activas a la hora de llegada. status, platform, route_type, trip_short_name (el número de tren) y los demás campos se leen exactamente igual que en el panel de salidas.

Una parada cerrada al descenso (drop_off_type 1 en el GTFS) se excluye, del mismo modo que una parada cerrada a la subida se excluye de las salidas.

Buenas prácticas

  • Almacene en caché lo que lee. El referencial es estático entre dos recargas manuales; volver a consultarlo en cada acción del usuario no aporta nada.
  • Indexe por el código UIC, no por el nombre. La SNCF retoca los nombres; los códigos son el identificador estable. source_ref permite encontrar el registro de origen en el conjunto de datos fuente, para auditoría.
  • Un código desconocido responde 404, con el código RAIL_STATION_NOT_FOUND; no debe confundirse con una búsqueda vacía, que es un 200 con total: 0.
  • No almacene en caché el panel de salidas como el referencial. Los flujos ferroviarios en tiempo real se actualizan aproximadamente cada dos minutos: consultar departures con más frecuencia devuelve las mismas estimaciones.