Skip to main content

Transport for London smart home integration, free and open source

Transport for London integration for Gladys Assistant

London Tube, Overground, DLR, Elizabeth line, tram and bus: line status and next arrivals.

View on GitHubAll integrations

The status of your London lines and the next arrivals at your stops in Gladys: Tube, London Overground, DLR, Elizabeth line, trams and buses, in real time.

The data comes from the TfL Unified API, the open data of Transport for London: no account needed, and an optional free key. Powered by TfL Open Data. This integration is not affiliated with Transport for London.

What you get​

  • A device per followed line: its status as TfL words it (“Minor delays”, “Part closure”…), a disruption level from 0 to 3, a disrupted yes/no and the reason given by TfL.
  • A device per watched stop (a Tube, DLR, Overground, Elizabeth line or tram station, or a bus stop), optionally filtered by lines and direction: minutes to the next arrival and to the following one, the line and destination of the next one, and whether one of its lines is disrupted.
  • Two dashboard widgets: the next arrivals of a stop, and the status of your followed lines.
  • Two scene triggers: line status changed (disrupted, getting worse, getting better, back to good service) and time to leave (1 to 20 minutes before an arrival).
  • Two scene actions: read the next arrivals of a stop, read the status of a line, each with a sentence ready to send by message or to a speaker.

Requirements​

  • Gladys Assistant 5.1.0 or later.
  • Internet access from the Gladys host (the integration calls api.tfl.gov.uk).
  • Optional: a free TfL app key, from the TfL API portal (sign up, then subscribe to the “500 Requests per min” product). Without it the integration uses the anonymous quota, enough for a few lines and stops.

Installation​

  1. In Gladys, open Integrations → Install from GitHub.
  2. Paste https://github.com/guim31/gladys-tfl and install.
  3. Open the integration's Configuration tab to follow lines and stops (below).

Configuration​

Settings​

  • Language of the texts: the language of the feature names (set when a device is created), of the statuses and of the sentences sent to your scenes. The reasons of the disruptions stay in English, as TfL publishes them.
  • Refresh interval: 1 minute (default) or 2 minutes.
  • TfL app key (optional): raises the quota. It is never written to the logs.

Following a line​

Use Follow a line with the name of a line: Victoria, Elizabeth line, Hammersmith & City, DLR, Tram, an Overground line (Liberty, Lioness, Mildmay, Suffragette, Weaver, Windrush) or a bus route number (73, N29). Then open the Discover tab and create the device.

Watching a stop​

  1. Find a stop: type a name (Oxford Circus, Brixton). The answer lists the stations and bus stops with their identifier in brackets, and the direction of a bus stop (→ Herne Hill).
  2. Add a stop: type the exact name or the identifier. Optional filters:
    • Lines: the lines to keep, separated by commas (Victoria, Central). Empty: every line.
    • Direction: a part of the destination or of the platform (Brixton, Southbound).
  3. Open the Discover tab and create the device.

A station with several networks (a “hub”, such as Brixton) is read through its TfL stations; National Rail services do not have TfL arrivals. The same stop can be added several times with other filters: each set of filters is its own device.

Removing, checking the state​

  • Stop following a line and Remove a stop (with the name shown in the status) stop the readings. The device stays in Gladys until you delete it.
  • Status lists the followed lines and watched stops, whether their device is created, the last read of TfL and the last error.

Devices​

Line (TfL · Victoria, TfL · Bus 73):

FeatureValue
Statusthe status in words, “Minor delays”, “Part closure + Minor…”
Disruption level0 good service, 1 minor, 2 severe or partial, 3 suspended
Disruption1 when the level is above 0, with history
Reasonthe reason given by TfL (English), or “No disruption”

Stop (TfL · Oxford Circus (Victoria · → Southbound)):

FeatureValue
Next arrivalminutes to wait (1440 when no arrival is announced)
Following arrivalminutes to the arrival after it
Line and destination“Victoria → Walthamstow Central”
Disruption1 when one of the lines of the stop (or of its filter) is disrupted

The night closure of the Tube (“Service closed”) is not a disruption. A planned work announced for later is not a disruption until it starts.

Dashboard widgets​

  • Next arrivals: pick a stop. One row per arrival (“Victoria → Brixton”, “07:45 · 3 min · Platform 6”), green when the line runs normally, orange when slightly disrupted, red when severely; the reason of a disruption on top.
  • TfL line status: every followed line with a created device, the most disrupted first, coloured the same way, with the first reason on top.

Scene triggers​

  • Line status changed: a followed line is disrupted, gets worse, gets better or is back to good service. Filters: the line (empty: any) and the events. Variables: line, event, status, level, previous level, reason.
  • Time to leave: an arrival at a watched stop is the chosen number of minutes away (1 to 20). Once per arrival and threshold. Filters: stop, line (as TfL writes it: Victoria, 73), threshold. Variables: stop, line, destination, platform, minutes, expected time.

Nothing fires at the first read after a start: what was already there is not news.

Scene actions​

  • Get the next arrivals: for a stop (and optionally a line), the minutes to the next and following arrivals, the line, destination, platform, expected time, whether a line is disrupted (1 or 0), and a sentence: “Victoria to Brixton at Oxford Circus: in 3 and 7 min”.
  • Get a line status: the status, level (0 to 3), its name, disrupted (1 or 0), the reason, and a sentence: “Victoria: Minor delays. Minor delays due to train cancellations.”

Scene examples​

  • Morning commute: at 7:30 on weekdays, Get a line status for the Northern line, then Continue only if disrupted = 1, then send the sentence by Telegram.
  • Leave now: trigger Time to leave on your bus stop, threshold 5 minutes, then flash a light and say “Your bus is 5 minutes away” on a speaker.
  • Back to normal: trigger Line status changed on the Elizabeth line with the event “Back to good service”, then send a message.

Data, refresh and quotas​

Every minute (or two), the integration reads, for the created devices only: one status request for every line involved (followed lines and lines of the watched stops), then one arrivals request per stop point (a station is one stop point, a hub up to four). TfL predicts arrivals about 30 minutes ahead. Up to 20 lines and 10 stops.

TfL asks for attribution (“Powered by TfL Open Data”) and limits the requests per key; anonymous use is limited harder. With many stops, add a free app key. See the TfL transport data terms.

Troubleshooting​

  • “TfL cannot be reached (…HTTP 429 (quota))”: too many requests on the anonymous quota. Add a free app key, or choose a 2-minute interval.
  • “(app_key refused)”: the key is wrong or not subscribed to a product on the TfL portal. Fix it, or empty the field.
  • No arrival: outside service hours, or a National Rail only station. Check the stop with Find a stop and its identifier.
  • The countdown stays at 1440: no arrival is announced by TfL right now.
  • More details: set LOG_LEVEL=debug on the container.

Limits​

  • Developed outside London against the real TfL API, without daily use there: feedback welcome.
  • Feature names are set when the device is created.
  • No delay nor cancellation per train: TfL publishes predicted times only.
  • The reasons of the disruptions are in English, as TfL publishes them.
  • National Rail services at shared stations are not covered.

Credits​

Powered by TfL Open Data. Contains OS data © Crown copyright and database rights. Inspired by the Home Assistant “London Underground” integration (Apache 2.0) and by the Entur and TTC integrations for Gladys.

Configuration settings​

These are the settings Transport for London asks for in its configuration screen in Gladys.

SettingTypeRequiredDescription
How it workssectionNoFollow lines and watch stops with the actions below, then create their devices in the Discover tab. Everything comes from TfL open data: no account needed, the key is optional.
Language of the textsselectNoLanguage of the feature names, of the statuses and of the sentences sent to your scenes. The reasons of the disruptions stay in English, as TfL writes them. Feature names are set when a device is created.
Refresh intervalselectNoHow often TfL is read for your created devices: one status request, plus one request per stop point.
TfL app key (optional)secretNoFree from the TfL API portal: it raises the quota to 500 requests a minute. Without it the integration works on the anonymous quota.

How to install Transport for London in Gladys​

  1. In Gladys, open Integrations: Transport for London appears in the catalog, next to the native integrations, with a community badge.
  2. Click Install. Gladys pulls the Docker image (ghcr.io/guim31/gladys-tfl:1.0.0), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration).
  3. Open the Configuration screen of the integration, fill in the settings, and save.
  4. You can also install it directly from its repository URL: https://github.com/guim31/gladys-tfl.

Transport for London requires Gladys >=5.1.0. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.

Not running Gladys yet? It is free and open source: follow the installation guide to get started.

About external integrations​

Transport for London is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by guim31, not by the Gladys core team.

Subscribe to the Gladys Assistant newsletter

A few emails per month about new releases and project news. Sent by Pierre-Gilles Leymarie, founder of the project. Unsubscribe anytime 🙂
Last updated on