1
Install the integration
Add the custom repository to HACS, download Brighton Bus Times and restart Home Assistant.
A simple, read-only connection
The Brighton Bus Times custom integration requests departure information from this website’s API. It does not need access to your Home Assistant installation, and it cannot control any of your devices.
What it does
Brighton Bus Times is a custom Home Assistant integration. It creates a device and a next-departure sensor for every selected stop, with the full departure board available as sensor attributes for dashboards, templates, announcements and automations.
2
Choose your stops
Search by stop name or enter NaPTAN stop IDs during the normal Home Assistant setup flow.
3
Use the new sensors
Each stop gets its own next-departure sensor and detailed departure-board attributes.
Where a recent vehicle has been matched reliably, a departure may include a live prediction. Otherwise, the published scheduled time is returned.
Install with HACS
HACS is the recommended installation method because it can notify you when an updated version is available.
- Open HACS in Home Assistant.
- Select Integrations.
- Open the menu in the top-right corner and choose Custom repositories.
- Enter
https://github.com/MrSleeps/Brighton-Bus-Times-Home-Assistant-Custom-Component. - Choose Integration as the category, then add the repository.
- Find Brighton Bus Times in HACS and select Download.
- Restart Home Assistant when prompted.
This is a custom integration and is not included in Home Assistant Core or the default HACS catalogue.
Manual installation
If you do not use HACS, download the integration from GitHub and copy the integration folder to:
/config/custom_components/brighton_bus_times/
The folder should directly contain files such as manifest.json, config_flow.py and sensor.py. Restart Home Assistant after copying the files.
Add the integration and choose your stops
- Open Settings → Devices & services.
- Select Add integration.
- Search for and select Brighton Bus Times.
- Keep the default API address,
https://brightonbustimes.co.uk. - Search for a stop using at least two characters, then select one or more results.
- Alternatively, enter NaPTAN stop IDs separated by commas or new lines.
- Submit the form to create the devices and sensors.
Finding a stop ID
Select a stop on the bus map to see its identifier. For example, Brighton Station (stop B2) is 149000006929. The integration validates selected stops before completing setup.
Enter at least two characters.
Selected stop codes
Change stops or refresh interval
Open Settings → Devices & services → Brighton Bus Times and select Configure. You can add or remove stops and choose a refresh interval from 15 to 300 seconds. The default is 30 seconds, please do not go below that (it's pointless due to BODS only updating every 30 seconds).
Devices, sensors and attributes
The integration creates one Home Assistant device and one numeric Next departure sensor for each selected stop. The sensor state is the number of minutes until the next bus; 0 means the bus is due.
Sensor attributes provide the rest of the departure-board information, including:
- route and destination;
- live or scheduled status;
- direction and stop information;
- vehicle and distance information when available;
- the complete
departureslist; - routes serving the stop;
- feed, cache and data-source metadata.
The numeric state works in ordinary entity cards, gauges, templates and automations. The detailed attributes can be used to build richer departure-board cards or announcements.
API limits and considerate use
The service is free to use for personal Home Assistant installations, but the API is rate-limited to keep the live bus service responsive for everyone.
| Guidance | What to do |
|---|---|
| Refresh interval | The integration permits 15–300 seconds and defaults to 30 seconds. The live source normally changes around this cadence, so faster updates provide little benefit. |
| Stops per installation | A maximum of 10 stops can be requested. The integration combines them into one API request rather than polling each stop separately. |
| Current allowance | The response rate-limit headers are authoritative. Limits may be adjusted as traffic and capacity change. |
| Limit exceeded | The API returns 429 Too Many Requests. Home Assistant should wait for its next normal polling interval rather than retrying immediately. |
| Caching | Responses may be served from a short-lived cache. Repeated requests do not force fresh operator data. |
Rate-limit headers
API responses may include headers describing the current request limit, remaining allowance and reset time. These are more reliable than copying a fixed number into an automation because the server policy can change.
Troubleshooting
- Integration not found: confirm HACS downloaded it, restart Home Assistant and clear the browser cache if necessary.
- Setup cannot continue: check the API address and confirm Home Assistant can make outbound HTTPS requests.
- No departures: confirm the stop code and check that the stop has upcoming scheduled services.
- Scheduled instead of live: the journey may be running, but no recent vehicle has been matched reliably.
- 429 response: increase the refresh interval under Configure and wait for the next scheduled update.
- Temporary failure: Home Assistant will try again at the next polling interval; avoid rapid manual refreshes.
Important notes
This is an independent service and is not affiliated with Home Assistant, Brighton & Hove Buses, Metrobus, the Department for Transport or the Bus Open Data Service. Departure predictions are provided on a best-effort basis and should not be treated as a guarantee.