Public transit information in smart home dashboards often depends on paid APIs or unreliable local feeds. ha-departures offers a pragmatic open-source alternative by integrating real-time departure times from the free Transitous API into Home Assistant. This custom integration balances ease of use with extensibility by providing a clean hub-and-sensor model and dynamic entity management through a GUI-based config flow.
how ha-departures integrates real-time transit data into Home Assistant
ha-departures is a custom integration written in Python tailored for Home Assistant. It connects to the Transitous API, an open-source transit data provider covering over 60 countries, to surface real-time departure times for public transit stops.
The core abstraction is a “hub,” representing a transit stop combined with user-selected transit routes or connections. Each hub dynamically manages multiple sensor entities, one per connection, that report upcoming departure times. This design fits neatly into Home Assistant’s entity model, allowing users to leverage native Lovelace UI cards or custom templates to visualize transit departures.
Under the hood, ha-departures follows Home Assistant’s custom component framework conventions. It implements a config flow that offers a GUI-driven setup experience, eliminating the need to edit YAML by hand. The integration fetches data from Transitous via HTTPS REST API calls and manages sensor updates accordingly.
A notable feature is runtime reconfiguration: users can add or remove connections within existing hubs through Home Assistant’s integration settings. This dynamic entity management means you don’t have to restart Home Assistant or manually modify config files to adjust your transit info.
The repository organizes the custom component code under custom_components/ha_departures/, following Home Assistant’s standard pattern. The integration is Python 3-based and depends on Home Assistant’s core libraries for entity registration and updates.
design choices and tradeoffs in ha-departures
What stands out in ha-departures is its clean separation of concerns with the hub and sensor model. This approach keeps the integration scalable and maintainable by encapsulating stop-level and per-connection logic distinctly. The config flow implementation enhances developer and user experience by offering an out-of-the-box GUI for setup and adjustments.
The code quality is pragmatic, focusing on clarity rather than complexity. The integration avoids unnecessary dependencies, which keeps its footprint minimal. Sensor entities are dynamically created and destroyed in response to the config flow state, which aligns well with Home Assistant’s dynamic device registry.
The tradeoff is the reliance on the Transitous API, which is free and covers many countries but may have variable data quality or availability compared to paid services. The integration does not appear to implement local caching or fallback strategies explicitly, so real-time accuracy depends fully on the external API’s responsiveness. This is a reasonable tradeoff for a community-driven integration aiming to avoid vendor lock-in and cost barriers.
Another practical consideration is that the integration is limited to data Transitous provides. This means if your transit system or routes are not well covered by Transitous, ha-departures won’t have data for those.
Overall, ha-departures strikes a balance between offering useful real-time transit info and maintaining a lightweight, user-friendly integration without overengineering.
installation and quick start with ha-departures
Installation can be done manually or via HACS (Home Assistant Community Store), which is the recommended method. Note that if ha-departures is not in your HACS default store, you’ll need to add it as a custom repository to make it available.
Manual installation steps from the README are as follows:
1. Using the tool of choice open the folder for your HA configuration (where you find `configuration.yaml`).
2. If you do not have a `custom_components` folder there, you need to create it.
3. In the `custom_components` folder create a new folder called `ha_departures`.
4. Download all the files from the `custom_components/ha_departures/` folder in this repository.
5. Place the files you downloaded in the new folder you created in `step 3`.
6. Restart Home Assistant
After installation, you can add the integration via Home Assistant’s GUI. The config flow will guide you through selecting transit hubs and routes.
who should consider using ha-departures?
If you use Home Assistant and want real-time public transit departure times integrated into your smart home dashboards without paying for commercial APIs, ha-departures is worth a look. It’s particularly relevant if your local transit system is covered by the Transitous API.
The integration shines with its dynamic entity management and GUI-driven setup, making it accessible even if you prefer to avoid manual YAML editing.
However, if you require guaranteed high availability or comprehensive coverage beyond what Transitous offers, or if you want offline caching of transit data, you’ll need to consider the limitations here.
In production, ha-departures offers a practical, no-frills solution for transit info that works well within Home Assistant’s ecosystem. Its codebase is straightforward enough to extend or troubleshoot if you want to adapt it to your needs.
In sum, ha-departures fills a niche for open, free transit data integration with a clean design and decent developer experience, though with the expected tradeoffs of relying on a community-driven API.
→ GitHub Repo: alex-jung/ha-departures ⭐ 71 · Python