Skip to content

04: Configuring a route's options (inc. adding real‐time)

Jump to bottom
Arjan edited this page Jul 21, 2026 · 7 revisions

After you have added a route, you can configure some options for that route.

Configuring a route's options

In the Home Assistant menu click: Settings > Devices & Services > Integrations, then click on the GTFS2 integration:

image

HA will list all the routes you have created with GTFS2. Find the route whose options you want to change, and click the Gear:

image

Route options

There are two route options:

Data refresh interval: Determines how often HA updates the route's sensor. Set it below the rate of departure so you don't show stale data in HA.

Tip

Don't set refresh interval too low, because every refresh queries the GTFS sqlite database. In this example, the bus line runs every 10 mins, so I reduced the refresh interval to 5.

Offset: The time in minutes that GTFS2 will use to determine if a departure is to be ignored. For example, if you need 10 minutes to get to the route's configured stop then you may not interested in departures that are in 5 minutes. You can use this option to make the route's sensor not show any departures that are less than 10 minutes from departing.

Configuring a route's real-time data

When available from the transport provider, you can extend the static data with real-time information, such as:

  • departures (per stop)
  • vehicle location
  • alerts

In this below example, a earlier configured service provides realtime data in a file locally stored. You can also use the url that points to the RT provider/source directly and this must be a source providing RT data in protobuf format. It provides tripupdates, for a departure stop without the use of an api-key

image

Warning

Alerts may prove to be flaky. It depends on your provider.

Field content for authorization via api-key's:

  • API key : usually a long string
  • API key name: depends on the service provider, known key-names are:
    • Authorization , default value and covers key previsously labeled as 'api_key'
    • x_api_key
    • apiKey
    • ocp_apim_subscription_key

You are free to type in any 'key name' that applies to your provider requirements

If your provider requires an authentication method with a (x_)api_key, you can apply this either in a 'header' or as part of the url 'query_string. Check with the provider which method applies

image

Example for this entity, you will find additional attributes:

gtfs_updated_at: "2023-12-17T06:28:17.493348+00:00"
origin_stop_alert: no info
destination_stop_alert: no info
attribution: Palmbus
device_class: timestamp
icon: mdi:bus
friendly_name: Palmbus B to Mouans
gtfs_rt_updated_at: "2023-12-17T06:29:18.728897+00:00"
next_departure_realtime: "2023-12-17T06:43:00+00:00"
delay: unknown
latitude: ""
longitude: ""

If real-time vehicle position data has been added to the options, they will need to be setup as a geojson sensor.

Configuration for acquiring real-time data, format SIRI

Warning

Status 2025-02-28: Initial implementation, unclear if this can be made near-generic and supported towards the future.

In almost all (known) cases, providers supply real-time data in the protobuf format. However, some may offer only SIRI structure (e.g. MTA New-York, SAE Strasbourg). Sadly also here there are deviations on the data-structure, data-labeling and data-content.

  • Covering MTA (tested) and possibly others if they use the same structure.
  • Applies only to start/end setup, as SIRI requires the stop as input. TBD if this can be extended the local-stops setup.
  • Real-time data has to be acquired as a file through the related SIRI Action, and the URL to the file used as a link in the config of the entity.
  • Strasbourg can be made working but (!) they only provide the API token via email requests. It is assumed that this is only for dev purposes.
  • If you have another source for SIRI real-time data, please enter a feature request.

Configuration for local stop departures

After you have properly configured sensors to acquire departure times of local stops, you can further fine-tune this:

image

  • Refresh interval: Default is 15min. Decrease this interval if you use a 'person' and are frequent on the move and need this new insight. Carefully adjust this setting, as it will have an effect on performance.
  • Radius: Default is 200m. GTFS2 will try to find stop within an approximate (!) radius around the location of the configured person or zone.
  • Departure in future: Default is 30min. The departures in the future from the moment of refresh, i.e. at the moment of refresh it will by default only select departures 30minutes in the future.
  • Offset: This allows to skip certain departures if they are not within reach. For example: if you need 10 minutes to get to the stop then you may not interested in departures that are upcoming in less than 10 minutes, as these are not feasible to reach.
  • Limit of local-stops: Default is 15. When setting up a radius in a densely serviced area, you may want to allow or prevent more stops being added to the sensor. Too many stops can lead to performance issues, but there is no reference as to when this occurs, use are your own risk
  • Configure real-time: You can use a URL to the trip data to show real-time data with your individual trips.

image

In this case, the data for real-time trip updates refers to a local file (www/gtfs2) which is downloaded using an Action

Note

Although entities of type 'zone' have a radius, this is not (yet) taken into account. This is to avoid a large zone triggering a massive set of data to be collected.

Tip

Depending on the frequency of transport around you, select a proper combination of refresh interval and departure in the future. In other words, with a low frequency of vehicles departing, the refresh interval does not have to be short but you can then select a larger value for departures in the future.

Clone this wiki locally