{"id":27714798,"url":"https://github.com/solarssk/ztm_warsaw","last_synced_at":"2026-05-20T01:09:59.019Z","repository":{"id":288827751,"uuid":"968638048","full_name":"solarssk/ztm_warsaw","owner":"solarssk","description":"🚌 Custom integration for Home Assistant to display real-time public transport departures from ZTM Warsaw.","archived":false,"fork":false,"pushed_at":"2025-08-09T22:39:02.000Z","size":54,"stargazers_count":6,"open_issues_count":1,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-08-10T00:19:29.857Z","etag":null,"topics":["home-assistant","integration","public-api","public-transportation","transport","warsaw"],"latest_commit_sha":null,"homepage":"https://github.com/solarssk/ztm_warsaw","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/solarssk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-18T12:57:11.000Z","updated_at":"2025-07-11T18:14:17.000Z","dependencies_parsed_at":"2025-04-19T21:39:09.012Z","dependency_job_id":"1487ff51-7a50-4eaf-9470-7dee160e3410","html_url":"https://github.com/solarssk/ztm_warsaw","commit_stats":null,"previous_names":["solarssk/ztm_warsaw"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/solarssk/ztm_warsaw","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solarssk%2Fztm_warsaw","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solarssk%2Fztm_warsaw/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solarssk%2Fztm_warsaw/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solarssk%2Fztm_warsaw/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/solarssk","download_url":"https://codeload.github.com/solarssk/ztm_warsaw/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solarssk%2Fztm_warsaw/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270071248,"owners_count":24522270,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-12T02:00:09.011Z","response_time":80,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["home-assistant","integration","public-api","public-transportation","transport","warsaw"],"created_at":"2025-04-27T00:58:12.977Z","updated_at":"2026-05-20T01:09:59.012Z","avatar_url":"https://github.com/solarssk.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🚍 ZTM Warsaw Integration for Home Assistant\n\n[![GitHub release](https://img.shields.io/github/v/release/solarssk/ztm_warsaw)](https://github.com/solarssk/ztm_warsaw/releases)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Home Assistant](https://img.shields.io/badge/Home%20Assistant-%F0%9F%A7%A1-blue)](https://www.home-assistant.io)\n[![HACS](https://img.shields.io/badge/HACS-Default-blue.svg)](https://hacs.xyz/)\n[![Validate with hassfest](https://github.com/solarssk/ztm_warsaw/actions/workflows/hassfest.yaml/badge.svg)](https://github.com/solarssk/ztm_warsaw/actions)\n[![custom_component](https://img.shields.io/badge/type-custom_component-red.svg)](https://github.com/solarssk/ztm_warsaw)\n\nZTM Warsaw Integration brings real-time public transport departure data from the City of Warsaw API directly into Home Assistant. Whether you're tracking buses, trams, or metro lines, this integration allows you to view live departures at a glance.\n\n\u003e Powered by data from [api.um.warszawa.pl](https://api.um.warszawa.pl) – the official public transport data provider.\n\n---\n\n## 🔧 Features\n\n- ✅ Real-time and static timetable support for buses, trams, metro, night, cemetery, express and local lines.\n- ✅ Supports multiple instances (you can monitor multiple stops and lines).\n- ✅ Displays current or upcoming departure as timestamp (compatible with UI and automations).\n- ✅ Optional display of up to 3 upcoming departures.\n- ✅ Automatically recognizes and handles no-schedule days, seasonal or partial-day routes.\n- ✅ Full Home Assistant UI configuration – no YAML needed.\n- ✅ Custom attributes: stop info, direction, timetable link and contextual notes.\n\n---\n\n## 📸 Screenshots\n\n### Integration Setup\n*Add your API key and stop info...*\n\n\u003cdiv align=\"center\"\u003e\u003cimg width=\"478\" alt=\"image\" src=\"https://github.com/user-attachments/assets/9a77591e-5b1a-4fe5-a29d-637d3c9b566c\" /\u003e\u003c/div\u003e\n\n### Entity Display\n\n\u003cdiv align=\"center\"\u003e\u003cimg width=\"555\" alt=\"image\" src=\"https://github.com/user-attachments/assets/ef709b81-1575-4718-9c39-f6c135cf3cca\" /\u003e\u003c/div\u003e\n\n### Attributes\n*Example entity showing departures with attributes like time, direction...*\n\n\u003cdiv align=\"center\"\u003e\u003cimg width=\"530\" alt=\"image\" src=\"https://github.com/user-attachments/assets/95cde9db-1182-41ba-9ae6-3187bd6a527c\" /\u003e\u003c/div\u003e\n\n---\n\n## ⚙️ Requirements\n\n- Home Assistant 2024.4+\n- API key from [City of Warsaw](https://api.um.warszawa.pl)\n\n---\n\n## 🧭 How to Get API Key?\n\n1. Go to [https://api.um.warszawa.pl](https://api.um.warszawa.pl)\n2. Register or log in\n3. Copy your key and paste it into the integration setup\n\n---\n\n## 📦 Installation\n\n### Manual installation:\n\n1. Download the latest version from [GitHub Releases](https://github.com/solarssk/ztm_warsaw/releases).\n2. Copy the `ztm_warsaw` folder to `/config/custom_components/`.\n3. Restart Home Assistant.\n\n### Installation via HACS:\n\n1. In Home Assistant, go to **HACS → Integrations**.\n2. Search for **Warsaw Public Transport**.\n3. Click **Download** and confirm.\n4. Restart Home Assistant.\n\n---\n\n## ⚙️ Configuration\n\nOnce installed:\n\n1. Go to **Settings → Devices \u0026 Services**\n2. Click **+ Add Integration**\n3. Search for **Warsaw Public Transport**\n4. Fill in:\n   - **API key**: You can get it at [https://api.um.warszawa.pl](https://api.um.warszawa.pl)\n   - **Stop ID** and **Stop number** (e.g., 7009 / 01)\n   - **Line number** (e.g., 151)\n   - **Number of departures to show**\n\nThe entity name will be generated automatically, e.g., `sensor.line_151_from_7009_01`.\n\n## 🔄 Reconfiguration\n\nYou can change the number of upcoming departures at any time by going to Settings → Devices \u0026 Services → Warsaw Public Transport → Configure of specific entity.\n\n## 🧾 Notes\n\nThis integration depends on the official City of Warsaw public API, which has several known limitations:\n\n- **🧭 Stop ID (busstopId) vs. Stop Pole (busstopNr)**\n  These are not the same — both are required for a valid query:\n  - `busstopId`: The ID of the stop (shared by all poles at that stop).\n  - `busstopNr`: The specific pole number — typically 01, 02, etc.\n  It’s the number painted on the physical bus/tram stop sign (słupek).\n  If a stop has multiple directions or platforms, each usually has a different pole number.\n\n- **📅 Schedule data availability is limited to the current day only**  \n  The API does not provide access to schedules for the upcoming days. This means:\n  - If a bus line (e.g., `E-2`) does not operate today (e.g., during weekends), it **won’t appear in the API at all**, even if it normally runs on weekdays. As a result, you won’t be able to add the integration for such a line on a day when it doesn’t operate, because the validation will fail with a `no_departures` error.\n  - If you add an entity when the line is active, it will work correctly.  \n    On days when the line is inactive, the entity will show a `60+ min` state and the following attribute will appear:\n    ```\n    note: \"No upcoming schedule available. Please verify on wtp.waw.pl or call 19115 for more information.\"\n    ```\n\n- **🔍 Some lines visible on wtp.waw.pl are not available in the API**  \n  The official journey planner (wtp.waw.pl) uses internal systems that may include more complete data than what’s exposed by the public API. If a line exists on the website but not in the integration — that’s a limitation of the API. Nothing can be done on my end.\n\n- **🌙 Night line schedules (e.g. `N01`, `N44`) and how they’re handled**  \n  ZTM (Zarząd Transportu Publicznego) treats the **entire night as part of the same service day**, so buses departing at `24:50`, `26:20`, etc. are **still part of the \"previous\" day’s schedule**.\n\n  This integration now correctly interprets such hours by **treating all times up to 4:59 as part of the previous service day**. This fix has been implemented starting from version `v1.0.2`.\n\n  - This ensures that **night departures do not disappear after midnight**.\n  - You can expect to see accurate countdowns like \"15 min\" even if it’s `02:00` and the bus is scheduled for `02:15` (`26:15` in the API).\n\n**Important Reminder**\nThese limitations are caused by the official API and are **out of scope of this integration**. I always recommend checking the official journey planner: [wtp.waw.pl](https://wtp.waw.pl)\n\n---\n\n## 🙌 Acknowledgments\n\nData provided by **Miasto Stołeczne Warszawa** and **Warszawski Transport Publiczny** via [api.um.warszawa.pl](https://api.um.warszawa.pl)\n\nThis project was fully planned and designed by me — from the concept and expected behavior of the integration, to how it interacts with the City of Warsaw’s public API. While I’m not a professional Python developer, I understand the essentials well enough to define the structure, logic, and features I wanted this integration to offer.\n\nTo bring it all to life, I used AI support (ChatGPT), which assisted me mainly with syntax, debugging, and implementation details. However, the overall design, behavior, and workflow were all thoughtfully laid out on my end.\n\nSpecial thanks to [@peetereczek](https://github.com/peetereczek/ztm), whose previous project inspired me at the beginning. Although this final version was built independently from scratch, his work gave me the initial push to approach things in my own way.\n\nIf you’re interested in improving or extending the project — go ahead! Contributions, ideas, and pull requests are always welcome.\n\n---\n\n## 📄 License\n\nMIT License\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsolarssk%2Fztm_warsaw","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsolarssk%2Fztm_warsaw","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsolarssk%2Fztm_warsaw/lists"}