Crea tu propio aviso del último tren con los datos abiertos de transporte de Japón

En el reel dije que muchas apps que cobran no inventaron nada. Toman datos públicos gratis y los hacen fáciles de usar. Para mostrarlo usé Shuden, una app del último tren que estoy construyendo, con una tarjeta en la pantalla bloqueada que cuenta los minutos hasta que tienes que salir del bar.

Shuden todavía no salió, y las pantallas del reel son una maqueta. Pero el corazón de la app lo puedes construir tú esta semana. Así se hace: consigues una clave para los datos abiertos de transporte de Japón, buscas la última salida de tu estación, la conviertes en una hora de "sal antes de" y la pones en tu pantalla bloqueada.

Datos gratis, mejor presentados

El ejemplo del reel fue Cal AI, la app de calorías que MyFitnessPal compró este año. TechCrunch publicó que factura más de 30 millones de dólares al año. Lo que me interesa es el patrón que hay detrás.

Japón publica gratis muchos datos de este tipo. Los horarios de trenes salen del Public Transportation Open Data Center (ODPT). La Agencia Meteorológica de Japón tiene un portal para desarrolladores con observaciones y avisos de desastres.

El valor está en juntar fuentes. Horarios, más tu ubicación, más la hora, y sabes el minuto exacto en que tienes que salir para alcanzar el último tren a casa. En Tokio, perderlo te cuesta un taxi carísimo.

Fotograma del reel: dos tarjetas, horarios de los datos abiertos de ODPT más tu ubicación del GPS del iPhone

Consigue una clave de ODPT

Todo empieza en el sitio para desarrolladores de ODPT. El registro es gratis.

  1. Lee primero las reglas en la página Rules/Guidelines. Las aceptas al registrarte.
  2. Abre User Registration y llena el formulario. Pide tu nombre en tu alfabeto y en letras latinas, una dirección, un teléfono y una afiliación. Si trabajas por tu cuenta, el formulario te dice que pongas Individual.
  3. Confirma tu correo con el enlace que te mandan.
  4. Espera. El sitio dice que la aprobación puede tardar hasta dos días hábiles, y te avisan por correo.
  5. Inicia sesión. Tu token de acceso, que la API llama consumer key, está en el botón Access token. La especificación completa de la API también está detrás del inicio de sesión.

Las preguntas van al centro por correo, no a las compañías de trenes. El sitio lo dice claramente.

Revisa qué líneas puedes usar de verdad

Japón no publica todos los horarios de trenes con las mismas condiciones. Hoy, en el catálogo de ODPT, los horarios por estación vienen en dos grupos.

Con la licencia normal, la Public Transportation Open Data Basic License: Tokyo Metro, Toei (metro, Tokyo Sakura Tram y Nippori Toneri Liner), el metro municipal de Yokohama, la línea Rinkai, Yurikamome, Tsukuba Express y Tama Monorail.

Solo con la Challenge Limited License: JR East (algunas líneas alrededor de Tokio, sin Shinkansen), Tokyu, Odakyu, Keio, Keikyu, Seibu, Tobu y Sotetsu.

La diferencia importa si quieres lanzar algo. La Basic License te deja hacer apps con o sin fines de lucro, siempre que la cumplas junto con la guía para desarrolladores. La licencia del Challenge está atada al Public Transportation Open Data Challenge 2026: usas los datos para participar en el concurso, una empresa que los use tiene que inscribirse y ofrecer las funciones gratis durante el concurso, y el permiso termina el 12 de marzo de 2027. JR East agrega su propia condición: no puedes usar sus datos para crear algo que compita con sus servicios.

Mi maqueta usaba la línea Keio Inokashira desde Shibuya, así que en la vida real esa versión solo sirve como proyecto para el concurso. Si quieres algo que puedas mantener, empieza con una línea de metro.

Cada operador ofrece varios tipos de datos. Para un aviso del último tren necesitas los horarios por estación (todas las salidas de una estación, por dirección y por tipo de día). Los horarios por tren (todas las paradas de un tren) sirven después, para ver dónde termina de verdad ese tren.

Pide el último tren

La API es REST normal con respuestas en JSON. Cada objeto tiene un ID como odpt.Station:TokyoMetro.Chiyoda.YoyogiUehara, y puedes listar las estaciones de una empresa con el endpoint odpt:Station filtrado por odpt:operator. Esta petición pide el horario de día laborable en Yoyogi-Uehara, línea Chiyoda, en dirección a Kita-Ayase:

curl -s "https://api.odpt.org/api/v4/odpt:StationTimetable?\
odpt:station=odpt.Station:TokyoMetro.Chiyoda.YoyogiUehara&\
odpt:railDirection=odpt.RailDirection:TokyoMetro.KitaAyase&\
odpt:calendar=odpt.Calendar:Weekday&\
acl:consumerKey=TU_CLAVE" > timetable.json

Sin clave, el servidor responde Require acl:consumerKey., así que si ves eso, te falta la clave en la URL. Los datos con licencia del Challenge salen de otro host, api-challenge.odpt.org.

La respuesta es una lista de horarios. Dentro de cada uno, odpt:stationTimetableObject tiene las salidas, cada una con odpt:departureTime, odpt:destinationStation y, cuando el operador lo incluye, la marca odpt:isLast. Las horas vienen como horas y minutos, y los últimos trenes salen después de medianoche, así que ordena 00:20 después de 23:50 antes de quedarte con el último:

jq -r '.[0]["odpt:stationTimetableObject"]
  | map(select(.["odpt:departureTime"]))
  | sort_by(.["odpt:departureTime"]
      | if . < "03:00" then "1" + . else "0" + . end)
  | last
  | "\(.["odpt:departureTime"]) to \(.["odpt:destinationStation"][0])"' timetable.json

Mira el destino antes de confiar en la hora. El último tren de una estación muchas veces no llega al final de la línea. Si tu estación está más allá de donde termina, ese no es tu último tren, y necesitas el último que de verdad te lleva a casa.

Conviértelo en una hora de salida

La salida del tren es solo la mitad de la respuesta. También necesitas cuánto tardas en caminar hasta el andén. Puedes dejar que la persona lo escriba, o preguntarle a MapKit: MKDirections con transporte a pie y calculateETA te devuelve el tiempo estimado en segundos.

La hora de "sal antes de" es la salida del tren menos la caminata. Después programas un aviso unos minutos antes con una notificación local:

import UserNotifications

func scheduleReminder(lastTrain: Date, walkMinutes: Int, warnMinutes: Int = 15) async throws {
    let leaveBy = lastTrain.addingTimeInterval(TimeInterval(-walkMinutes * 60))
    let remindAt = leaveBy.addingTimeInterval(TimeInterval(-warnMinutes * 60))

    let content = UNMutableNotificationContent()
    content.title = "Sal en \(warnMinutes) min"
    content.body = "Tu último tren sale a las \(lastTrain.formatted(date: .omitted, time: .shortened))."

    let parts = Calendar.current.dateComponents([.year, .month, .day, .hour, .minute], from: remindAt)
    let trigger = UNCalendarNotificationTrigger(dateMatching: parts, repeats: false)
    try await UNUserNotificationCenter.current().add(
        UNNotificationRequest(identifier: "last-train", content: content, trigger: trigger))
}

Pide primero permiso para notificaciones, y recuerda que un horario es un plan, no una promesa. Los retrasos existen.

La tarjeta de la pantalla bloqueada del reel

Fotograma del reel: una pantalla bloqueada de iPhone recreada con una tarjeta Last train home en cuenta regresiva, salir antes de las 0:12, de Shibuya a Kichijoji por la línea Inokashira a las 0:20, y un aviso debajo. Es una maqueta, no la app real

Lo que muestra la maqueta es una Live Activity: una tarjeta en la pantalla bloqueada con la cuenta regresiva, la hora de salida y la línea, más la notificación debajo. Así la conectaría yo con ActivityKit de Apple.

  1. Agrega una extensión de widget y define un tipo ActivityAttributes: datos fijos como la línea y las estaciones, y un ContentState con la hora de salir y la del tren.
  2. Iníciala desde la app mientras está en primer plano con Activity.request(attributes:content:pushType:). Apple explica que también puedes iniciarla en segundo plano con un app intent que cumpla LiveActivityIntent, por ejemplo un botón en el Centro de control.
  3. Para la cuenta regresiva, usa Text(timerInterval:countsDown:) de SwiftUI. El sistema dibuja el temporizador solo, así que no tienes que mandar una actualización cada segundo.
  4. Pon el staleDate en la hora del tren, para que la tarjeta se vea desactualizada cuando el tren ya se fue.

Dos límites de la documentación de Apple que conviene tener en cuenta. Una Live Activity puede estar activa hasta ocho horas, y después puede quedarse en la pantalla bloqueada hasta cuatro horas más. Iníciala en la noche, no en el desayuno.

Antes de publicar algo

La guía para desarrolladores de ODPT tiene reglas fáciles de pasar por alto y rápidas de cumplir:

  • Indica en la app que los datos vienen del Public Transportation Open Data Center y que su exactitud no está garantizada.
  • Pon un correo para preguntas sobre tu app, para que la gente no llame a la compañía de trenes.
  • Muestra cuándo descargaste el horario, y actualízalo dentro de la semana en que el centro anuncia un cambio.
  • No vuelvas a publicar los datos crudos de forma que otros los puedan reutilizar. Mostrarlos dentro de tu app está bien. Servirlos desde tu propia API pública, no.

Si el transporte no es lo tuyo, la misma idea funciona con otros datos. Hay una lista en GitHub llamada Public APIs con cientos de fuentes gratis. Elige una y piensa a quién le resolvería un problema si la juntas con otra cosa.

← Todos los artículos