Home
This is a Home Assistant integration for Metlink, Wellington's public transport provider.
If you do not use Home Assistant, this is not for you. If you are not living in Greater Wellington, New Zealand, this is probably not for you.
This integration is not officially supported by Metlink or the Greater Wellington Regional Council. It has been made by a private individual on a voluntary basis, using the Open Data API provided by GWRC for the purpose.
Currently the Metlink API is free to access with no limitations stated, and no commercial license terms published, though there is a hint in the developer site that limits are present. If in future limits are put in place, it may limit the number of stops you can add, or even stop returning results for a single stop part way through the day/week/month or whatever period they limit the usage over. If this happens, it may be necessary to reduce the frequency of updates, which may make the realtime data less useful. I will try to keep the integration usable under a free limit for at least one stop.
Add the integration using HACS or by manual installation. If you need help with manual installation, then HACS has very good installation instructions.
After installing and restarting Home Assistant, go into the Configuration screen and select Integrations. Click the + Add Integration button, and search for "Metlink".
When installing, you will be prompted for an API key. Keys can be obtained by registering at the Metlink Developer Portal. After registering, you will need to subscribe to the Metlink Open Data API (which is currently the only API offered, though they confusingly list it twice to leave you wondering which one you need to subscribe to - either will do)
After a valid API key has been entered, you will be prompted for the first stop to setup.
Only the first field, Stop ID is mandatory. This should be the four digit number from the bus or ferry stop sign, or the 4 letter code for the train or cable car stop. If you don't know, the main Metlink website will tell you - click on the stop on the map to see it.
The fields Route filter and Destination filter are optional, in case there are a large number of buses passing through a stop, and you are only interested in a particular one. The route filter should be the route number for buses, or the three letter line abbreviation for trains. Again, these can be searched on the main Metlink site if you are not sure. The destination filter can further refine for routes that split or can be used instead if there are multiple routes to the same destination. Only the final destination is supported for filtering, as only the stop departures predictions API is used, so no information on intermediate stops is available. Either the stop id for the final destination, or its exact name from the API data is supported (initially I thought the name would be more user friendly, until I realised the exact name used in the API can differ from the website, and may not be obvious in all cases, so beware).
The Number of departures field can optionally be increased to track more upcoming departures. The default is to just track one at a time. The upper limit is the number of departures returned by the API, which may depend on how many routes use the stop and how busy it is, but probably around 10 from observation. Additional departures appear with their attributes suffixed by _2, _3, ...etc for easy extraction in lovelace cards.
If you want to keep adding more stops, you can tick the checkbox.
Here is a sample using a standard Entities card with data for 4 stops: WELL (Wellington Train Station), 5016 (Wellington Station Bus Stop D), showing 3 departures, LAMB (Lambton Quay Cable Car), and 9999 (Day's Bay Wharf).
Just simply adding the entity by itself will result in output like the LAMB cable car and 9999 ferry rows in the example above. The output for WELL train and 5016 bus departures has been prettied up a bit by showing the description attribute instead of the state on the first row, and customizing the icon and title on the second row. For subsequent departures, the second row also needs to use the departure_2 etc attribute and explicitly set the format to relative.
Unfortunately the UI editor is not able to handle attributes, so the lovelace configuration needs to be entered as code to use them. Here is the lovelace configuration for the above:
title: Metlink
type: entities
entities:
- section:
- entity: sensor.metlink_WELL
type: attribute
attribute: description
- entity: sensor:metlink_WELL
name: Due
icon: 'mdi:clock'
- section
- entity: sensor.metlink_5016
type: attribute
attribute: description
- entity: sensor.metlink_5016
name: Due
icon: 'mdi:clock'
- entity: sensor.metlink_5016
type: attribute
attribute: description_2
name: Metlink 5016/2
- entity: sensor.metlink_5016
name: Due
icon: 'mdi:clock'
type: attribute
attribute: departure_2
format: relative
- entity: sensor.metlink_5016
type: attribute
attribute: description_3
name: Metlink 5016/3
- entity: sensor.metlink_5016
name: Due
icon: 'mdi:clock'
type: attribute
attribute: departure_3
format: relative
- entity: sensor.metlink_LAMB
- entity: sensor.metlink_9999The stop configuration can be changed after installation. If you need to change your API key for some reason, you will need to delete the whole integration and set it up again.
In the Configuration menu, select Integrations.
Find the Metlink integration and click on Configure.
To add another stop, fill in the details the same as in the initial configuration step, except there is no checkbox because you can easily re-enter the configuration to add another.
At the top, is a dropdown with existing stops.
Unchecking a stop and submitting will remove it from the configuration. You can leave the rest of the form blank if you are removing stops.