TfL Journey Planner + Disruption Checks
Use this skill when the user wants a TfL journey plan and needs disruption awareness.
Reference: https://tfl.gov.uk/info-for/open-data-users/api-documentation
Script helper
Use scripts/tfl_journey_disruptions.py for a quick journey + disruption check.
Examples:
python3 scripts/tfl_journey_disruptions.py \"940GZZLUSTD\" \"W1F 9LD\" --depart-at 0900
python3 scripts/tfl_journey_disruptions.py --from \"Stratford\" --to \"W1F 9LD\" --arrive-by 1800
Notes:
- If the API returns disambiguation options, pick one and retry with its
parameterValue. - If you have TfL API keys, set
TFL_APP_ID and TFL_APP_KEY in the environment.
Inputs to collect
- From: postcode, stop/station name, place name, or lat,lon
- To: postcode, stop/station name, place name, or lat,lon
- Time + intent: depart at or arrive by (and date if not explicit)
- Optional: mode or accessibility constraints if the user mentions them
If any of these are missing or ambiguous, ask the user for clarification.
Resolve locations
Prefer postcodes when available. Otherwise, resolve place names and stations:
- If input looks like a UK postcode, use it directly as
{from} or {to}. - If input is lat,lon, use as-is.
- If input is a stop or station name, try
StopPoint/Search/{query} and choose a hub or the relevant NaPTAN ID. - If the search or journey result returns disambiguation, show the top options (common name + parameterValue) and ask the user to pick.
- When unsure, ask a clarifying question rather than guessing.
Plan journeys
Call:
/Journey/JourneyResults/{from}/to/{to}?date=YYYYMMDD&time=HHMM&timeIs=Depart|Arrive
Guidelines:
- If the user says "arrive by" use
timeIs=Arrive; otherwise default to Depart. - If the date is not provided, ask. If the user implies "now", you can omit date/time.
Extract candidate routes
From the response, take the first 1-3 journeys. For each, capture:
- Duration and arrival time
- Public transport legs (mode, line name, direction)
- Line IDs for disruption checks
Line IDs usually appear in leg.routeOptions[].lineIdentifier.id or leg.line.id. Ignore walking legs.
Disruption checks
For each journey, collect unique line IDs and call:
/Line/{ids}/Status
Treat a route as disrupted if any line status is not "Good Service" or includes a reason. Summarize the severity and reason.
Optionally, check station-specific issues with /StopPoint/{id}/Disruption when relevant.
Response strategy
- If the top route has no disruptions, recommend it and say no active disruptions were found.
- If the top route is disrupted, warn first, then propose 1-2 alternative routes from other journeys.
- If all routes are disrupted, still recommend the best option but list the disruption warnings and alternatives.
- If the journey is for a future time (later today or another day), note that disruption statuses are current and may change by the travel time (for example: "Minor Delays now; this may change by morning").
- Always invite the user to confirm a route or provide clarifications.