Services

The integration provides a service to manually refresh departure data.

openpublictransport.refresh_departures

Manually refresh departure data from the API outside of the normal update interval.

Description

This service triggers an immediate API call to fetch the latest departure information. Use this when you need up-to-date data without waiting for the next scheduled update.

Parameters

Parameter	Required	Description
`entity_id`	No	Specific entity to refresh. If omitted, all entities are refreshed.

Examples

Refresh All Sensors

service: openpublictransport.refresh_departures

Refresh Specific Sensor

service: openpublictransport.refresh_departures
data:
  entity_id: sensor.openpublictransport_dusseldorf_hauptbahnhof

Refresh Multiple Sensors

service: openpublictransport.refresh_departures
data:
  entity_id:
    - sensor.openpublictransport_dusseldorf_hauptbahnhof
    - sensor.openpublictransport_essen_hauptbahnhof

Use Cases

Button Card for Manual Refresh

Create a button in your dashboard to manually refresh data:

type: button
name: Refresh Departures
icon: mdi:refresh
tap_action:
  action: call-service
  service: openpublictransport.refresh_departures
  service_data:
    entity_id: sensor.openpublictransport_dusseldorf_hauptbahnhof

Automation: Refresh When Arriving Home

automation:
  - alias: "Refresh departures when arriving home"
    trigger:
      - platform: state
        entity_id: person.john
        to: home
    action:
      - service: openpublictransport.refresh_departures
        data:
          entity_id: sensor.openpublictransport_dusseldorf_hauptbahnhof

Automation: Refresh Before Morning Commute

automation:
  - alias: "Refresh departures before commute"
    trigger:
      - platform: time
        at: "07:00:00"
    condition:
      - condition: time
        weekday:
          - mon
          - tue
          - wed
          - thu
          - fri
    action:
      - service: openpublictransport.refresh_departures
        data:
          entity_id: sensor.openpublictransport_dusseldorf_hauptbahnhof

Script: Refresh and Notify

script:
  refresh_and_notify_departures:
    alias: "Refresh and Notify Departures"
    sequence:
      - service: openpublictransport.refresh_departures
        data:
          entity_id: sensor.openpublictransport_dusseldorf_hauptbahnhof
      - delay:
          seconds: 2
      - service: notify.mobile_app
        data:
          title: "Next Departure"
          message: >
            {{ states('sensor.openpublictransport_dusseldorf_hauptbahnhof') }} -
            {{ state_attr('sensor.openpublictransport_dusseldorf_hauptbahnhof', 'next_departure_minutes') }} min

Rate Limiting Considerations

Warning

While the refresh service bypasses the normal update interval, it still counts against the daily API rate limit.

Each refresh counts as one API call
The integration tracks daily API calls
If the rate limit is reached, refreshes will fail
A repair issue will be created if rate limiting is triggered

Best Practices

Don't call too frequently - Give time for API response before triggering again
Use in specific scenarios - Arriving home, before leaving, etc.
Combine with normal updates - Don't rely solely on manual refreshes
Monitor API usage - Check the diagnostics for call counts

openpublictransport.plan_trip

Plan a route from origin to destination, returning connections with transfers and real-time delay information.

Parameters

Parameter	Required	Description
`provider`	Yes	Provider ID — any EFA-based provider (e.g. `vrr`, `kvv`, `bvg`, `mvv`, `sbb`, `oebb`)
`origin`	Yes	Origin stop name (e.g. `Holthausen`)
`origin_city`	No	City of origin stop for more precise results
`destination`	Yes	Destination stop name (e.g. `Hauptbahnhof`)
`destination_city`	No	City of destination stop for more precise results

Examples

Basic Trip Query

service: openpublictransport.plan_trip
data:
  provider: vrr
  origin: Holthausen
  origin_city: Düsseldorf
  destination: Hauptbahnhof
  destination_city: Düsseldorf

Cross-City Trip

service: openpublictransport.plan_trip
data:
  provider: vrr
  origin: Hauptbahnhof
  origin_city: Düsseldorf
  destination: Hauptbahnhof
  destination_city: Essen

Example Response

The service returns trip data via a openpublictransport_trip_result event:

{
  "origin": "Holthausen, Düsseldorf",
  "destination": "Hauptbahnhof, Düsseldorf",
  "departure_time": "2026-04-09T08:15:00+02:00",
  "arrival_time": "2026-04-09T08:42:00+02:00",
  "duration_minutes": 27,
  "transfers": 1,
  "legs": [
    {
      "line": "U79",
      "direction": "Duisburg Meiderich",
      "departure_stop": "Holthausen",
      "departure_time": "08:15",
      "arrival_stop": "Düsseldorf Hbf",
      "arrival_time": "08:35",
      "delay": 2,
      "platform": "1"
    },
    {
      "line": "RE5",
      "direction": "Koblenz Hbf",
      "departure_stop": "Düsseldorf Hbf",
      "departure_time": "08:40",
      "arrival_stop": "Düsseldorf Hbf",
      "arrival_time": "08:42",
      "delay": 0,
      "platform": "3"
    }
  ],
  "connection_feasible": true,
  "transfer_risk": "low"
}

Use in Automation

automation:
  - alias: "Plan morning commute"
    trigger:
      - platform: time
        at: "07:00:00"
    action:
      - service: openpublictransport.plan_trip
        data:
          provider: vrr
          origin: Holthausen
          origin_city: Düsseldorf
          destination: Hauptbahnhof
          destination_city: Düsseldorf

For full details see the Trip Planner guide.

openpublictransport.check_delays

Check for delayed departures and fire an openpublictransport_delay_alert event.

Parameters

Parameter	Required	Description
`entity_id`	Yes	Sensor entity to check
`delay_threshold`	No	Minimum delay in minutes to count as delayed (default: 5)
`line`	No	Filter to a specific line (e.g. `U79`)

Example Call

service: openpublictransport.check_delays
data:
  entity_id: sensor.openpublictransport_dusseldorf_hauptbahnhof
  delay_threshold: 5
  line: "U79"

Response

Returns a list of delayed departures. Additionally fires an openpublictransport_delay_alert event with:

Field	Description
`entity_id`	The checked entity
`delayed_count`	Number of delayed departures
`max_delay`	Highest delay in minutes
`lines`	List of affected lines
`departures`	Full list of delayed departure objects

Example Automation

automation:
  - alias: "Notify on checked delays"
    trigger:
      - platform: event
        event_type: openpublictransport_delay_alert
    condition:
      - condition: template
        value_template: "{{ trigger.event.data.delayed_count > 0 }}"
    action:
      - service: notify.mobile_app
        data:
          title: "Delay Alert"
          message: >
            {{ trigger.event.data.delayed_count }} delayed departure(s).
            Max delay: {{ trigger.event.data.max_delay }} min.
            Lines: {{ trigger.event.data.lines | join(', ') }}

openpublictransport.announce_departure

Get a spoken-language departure announcement for use with any TTS service.

Parameters

Parameter	Required	Description
`entity_id`	Yes	Sensor entity to announce from
`index`	No	Departure index (default: 0 = next departure)

Example Call

service: openpublictransport.announce_departure
data:
  entity_id: sensor.openpublictransport_dusseldorf_hauptbahnhof
  index: 0

Response

{
  "text": "U79 Richtung Wittlaer fährt in 3 Minuten von Gleis 2. Verspätung: 3 Minuten."
}

TTS Automation Example

automation:
  - alias: "Morning TTS departure announcement"
    trigger:
      - platform: time
        at: "07:30:00"
    condition:
      - condition: time
        weekday: [mon, tue, wed, thu, fri]
    action:
      - service: openpublictransport.announce_departure
        data:
          entity_id: sensor.openpublictransport_dusseldorf_hauptbahnhof
          index: 0
        response_variable: result
      - service: tts.speak
        target:
          entity_id: tts.google_translate
        data:
          message: "{{ result.text }}"