Skip to content

2. Concepts

Jump to bottom
Filip Chochół edited this page May 19, 2026 · 2 revisions

🧭 Concepts

Stop ID vs. Stop Number

These are two separate values — both required.

Term Field name What it is Example
Stop ID busstopId Numeric ID shared by all poles at one stop location 7009
Stop Number busstopNr The specific pole (platform) at that location 01, 02

Think of it like a building: the Stop ID is the street address, and the Stop Number is the apartment number.

The pole number is printed on the physical sign at the stop (the "słupek"). If a stop has multiple directions or platforms, each has a different pole number.

Night Lines and the ZTM Service Day

ZTM defines a service day as running from 5:00 AM to 4:59 AM the next calendar day. This means:

  • A bus departing at 01:30 on Tuesday is still part of Monday's schedule
  • The API returns times like 25:30 (meaning 1:30 AM the next day)
  • The integration correctly handles this — night departures won't disappear after midnight

Night lines (e.g. N01, N44, N64) operate exclusively during these late/early hours and are handled correctly.

Schedule Data Limitations

The ZTM API only provides today's schedule. This has a few consequences:

  • Lines that don't run today won't appear in the API. If you try to add a line (e.g. E-2) on a day it doesn't operate, setup will fail with a no_departures error.
  • Existing sensors for lines that don't run today will show 60+ min state with a note:
    "No upcoming schedule available. Please verify on wtp.waw.pl or call 19115."
  • Some lines visible on wtp.waw.pl may not be available via the API — the website uses internal systems with more complete data. This is a limitation of the public API and cannot be worked around.

Sensor State

The sensor value is a timestamp (datetime) of the next upcoming departure. This makes it compatible with:

  • HA UI cards that display countdown timers
  • Automations that trigger based on departure time
  • History graphs

When no departure is available, the sensor state is unknown.

How Updates Work

The integration fetches the full day's timetable once per hour from the ZTM API. It does not poll every minute — instead, each sensor schedules an exact internal callback at the moment of each departure. This keeps the system efficient even with many sensors active.

If the API is temporarily unreachable, the sensor continues showing the last known timetable and retries on the next hourly cycle.

Clone this wiki locally