A Home Assistant custom integration for Transport Victoria data published on the Transport Victoria Open Data Portal (GTFS schedule and GTFS Realtime). It shows upcoming departures at a chosen stop (metro trains, trams, buses, regional buses, V/Line) and merges GTFS schedule data with GTFS Realtime delays and service alerts.
Schedule data is stored locally in SQLite after download; realtime feeds require a free API key from the open data portal.
- Departure sensors — next departures with scheduled time, delay, route, headsign, platform, and trip id where available.
- Disruption sensor — binary sensor when service alerts apply to your watch.
- Config flow — pick mode, find a stop by name, distance from home, or map location; optional specific destination routing.
- Rate limiting — shared async limiter so multiple watches stay within the open data API limits (24 requests / 60 seconds across all realtime endpoints).
- Home Assistant 2026.1 or newer (2026.x). The minimum is set in
hacs.json(homeassistant) for HACS; custom integrationmanifest.jsondoes not use that field. This integration targets current APIs (runtime_data, config flow, etc.). - A subscription key from the Transport Victoria Open Data Portal for realtime feeds (trip updates and service alerts). Same key is sent as HTTP header
KeyID. Under My Account → Subscription Keys (self-service, no approval queue).
Static GTFS schedule downloads do not require a key.
- Open HACS → Integrations → ⋮ → Custom repositories.
- Add this repository URL, category Integration.
- Install Transport Victoria and restart Home Assistant.
- Settings → Devices & services → Add integration → search Transport Victoria.
Copy the custom_components/transport_victoria folder into your Home Assistant config/custom_components/ directory, then restart Home Assistant and add the integration from the UI.
config/
└── custom_components/
└── transport_victoria/
├── manifest.json
└── ...
Configuration is done entirely in the UI.
- API key — validated with a test request to the realtime API.
- Mode — e.g. Metro Trains, Trams, Buses, Regional Buses, V/Line.
- Stop — search by name, list by distance from the Home Assistant zone, or drop a pin on the map.
- Destination — all destinations (default) or a specific destination with route validation.
- Name — used for entity ids (e.g.
sensor.transport_victoria_<name>_next).
On first use the integration downloads and imports the relevant GTFS bundle(s); this can take a minute. Data is refreshed on a weekly schedule and when you add modes that need new bundles.
Options (after setup): rename the watch, adjust polling interval, toggle realtime updates — see the integration’s Configure in the UI.
Per watch (each config entry), you typically get:
| Entity | Description |
|---|---|
| Departure sensors | Minutes to next departures (multiple slots: next, next_2, …) |
| Disruption binary sensor | On when an active service alert matches the watch |
Vehicle / route tracking entries (if enabled in your build) expose additional entities such as device trackers.
Exact entity ids follow Home Assistant’s naming; see Developer tools → States after setup.
All datasets are published by Transport Victoria on the open data portal.
| Data | Source |
|---|---|
| Static timetables | GTFS Schedule (ZIP, updated regularly) |
| Delays & cancellations | GTFS Realtime trip updates |
| Disruptions | GTFS Realtime service alerts |
Dataset terms: CC BY 4.0 where applicable — see the portal’s Public Transport organisation for current licence text.
This integration is not affiliated with Transport Victoria or the Victorian Government.
Clone the repo and use the included Compose stack to run Home Assistant with this component mounted read-only.
Prerequisites: Podman with Compose (or Docker Compose with minor script tweaks). The helper scripts assume podman compose.
./scripts/dev.sh up # start HA → http://localhost:8123
./scripts/dev.sh logs # follow logs
./scripts/dev.sh restart # reload after code changes
./scripts/dev.sh reset # wipe local dev config under dev/ (ignored by git)
./scripts/dev.sh downThe dev/ directory is gitignored and holds your local ha-config and downloaded GTFS data.
Tests (Python 3.13 in CI):
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements_test.txt
pytest tests/ -q # run from repository root so `custom_components` imports resolveStrict typing: mypy is configured via mypy.ini for maintainers who run it locally.
custom_components/transport_victoria/ # integration package
tests/ # pytest suite
.github/workflows/ # CI: tests, HACS, hassfest
compose.yaml # local HA dev service
scripts/dev.sh # Podman-focused dev helpers
Bug reports and pull requests are welcome: Issues.
GTFS and GTFS Realtime are industry-standard formats; this integration uses the gtfs-realtime-bindings Python package to decode protobuf feeds.
Thanks to bremor/public_transport_victoria for the earlier Home Assistant custom component that brought PTV departures into HA. That project uses the PTV Timetable API (developer id + API key). This integration is a separate design: it uses Transport Victoria open data (GTFS schedule + GTFS Realtime) instead, but the idea of monitoring Victorian public transport in Home Assistant owes a debt to that work.