python-openpublictransport 0.2.0__tar.gz → 0.3.0__tar.gz

{python_openpublictransport-0.2.0 → python_openpublictransport-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-openpublictransport
-Version: 0.2.0
+Version: 0.3.0
 Summary: Python library for public transport APIs (EFA, OTP2, TRIAS, FPTF, HAFAS, GTFS-RT)
 License: MIT
 Requires-Python: >=3.11

{python_openpublictransport-0.2.0 → python_openpublictransport-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-openpublictransport"
-version = "0.2.0"
+version = "0.3.0"
 description = "Python library for public transport APIs (EFA, OTP2, TRIAS, FPTF, HAFAS, GTFS-RT)"
 readme = "README.md"
 license = { text = "MIT" }

{python_openpublictransport-0.2.0 → python_openpublictransport-0.3.0}/src/openpublictransport/const.py

@@ -28,7 +28,6 @@ PROVIDER_TRANSITOUS = "transitous"
 PROVIDER_DB = "db"
 PROVIDER_VBN_OTP = "vbn_otp"
 PROVIDER_VBN_TRIAS = "vbn_trias"
-PROVIDER_OPT = "openpublictransport"
 PROVIDER_OTP_CUSTOM = "otp_custom"
 PROVIDER_NATIONAL_RAIL = "national_rail"
 PROVIDER_REJSEPLANEN = "rejseplanen"
@@ -39,9 +38,30 @@ PROVIDER_BART_US = "bart_us"
 PROVIDER_DART_US = "dart_us"
 PROVIDER_IRISHRAIL_IE = "irishrail_ie"
 PROVIDER_TPG_CH = "tpg_ch"
+PROVIDER_VMV = "vmv"
+PROVIDER_GVH = "gvh"
+PROVIDER_NAHSH = "nahsh"
+PROVIDER_INSA = "insa"
+PROVIDER_VMT = "vmt"
+PROVIDER_SAARVV = "saarvv"
+PROVIDER_VAO_AT = "vao_at"
+PROVIDER_VSN = "vsn"
+PROVIDER_VOS = "vos"
+PROVIDER_NVV = "nvv"
+PROVIDER_VBN_HAFAS = "vbn_hafas"
+PROVIDER_TRIMET_US = "trimet_us"
+PROVIDER_IRAIL_BE = "irail_be"
+PROVIDER_SL_SE = "sl_se"
+PROVIDER_TTC_CA = "ttc_ca"
+PROVIDER_HONGKONG = "hongkong"
+PROVIDER_WIENERLINIEN = "wienerlinien_at"
+PROVIDER_TFL = "tfl_uk"
+PROVIDER_TFNSW = "tfnsw_au"
+PROVIDER_DIGITRANSIT = "digitransit_fi"
+PROVIDER_GOLEMIO = "golemio_cz"
 
 # API base URLs
-API_BASE_URL_VRR = "https://openservice-test.vrr.de/static03/XML_DM_REQUEST"
+API_BASE_URL_VRR = "https://openservice.vrr.de/static03/XML_DM_REQUEST"
 API_BASE_URL_KVV = "https://projekte.kvv-efa.de/sl3-alone/XSLT_DM_REQUEST"
 API_BASE_URL_HVV = "https://hvv.efa.de/efa/XML_DM_REQUEST"
 API_BASE_URL_TRAFIKLAB = "https://realtime-api.trafiklab.se/v1"

{python_openpublictransport-0.2.0 → python_openpublictransport-0.3.0}/src/openpublictransport/providers/__init__.py

@@ -18,7 +18,6 @@ from ..const import (
     PROVIDER_NVBW,
     PROVIDER_NWL,
     PROVIDER_OEBB,
-    PROVIDER_OPT,
     PROVIDER_OTP_CUSTOM,
     PROVIDER_RMV,
     PROVIDER_RVV,
@@ -42,6 +41,27 @@ from ..const import (
     PROVIDER_DART_US,
     PROVIDER_IRISHRAIL_IE,
     PROVIDER_TPG_CH,
+    PROVIDER_VMV,
+    PROVIDER_GVH,
+    PROVIDER_NAHSH,
+    PROVIDER_INSA,
+    PROVIDER_VMT,
+    PROVIDER_SAARVV,
+    PROVIDER_VBN_HAFAS,
+    PROVIDER_NVV,
+    PROVIDER_VOS,
+    PROVIDER_VSN,
+    PROVIDER_VAO_AT,
+    PROVIDER_TRIMET_US,
+    PROVIDER_IRAIL_BE,
+    PROVIDER_SL_SE,
+    PROVIDER_TTC_CA,
+    PROVIDER_HONGKONG,
+    PROVIDER_WIENERLINIEN,
+    PROVIDER_TFL,
+    PROVIDER_TFNSW,
+    PROVIDER_DIGITRANSIT,
+    PROVIDER_GOLEMIO,
 )
 from .avv import AVVProvider
 from .base import BaseProvider
@@ -50,7 +70,6 @@ from .bsvg import BSVGProvider
 from .bvg import BVGProvider
 from .db import DBProvider
 from .ding import DINGProvider
-from .gtfsde import OPTProvider
 from .hvv import HVVProvider
 from .hvv_gti import HVVGTIProvider
 from .kvv import KVVProvider
@@ -81,6 +100,27 @@ from .bart import BARTProvider
 from .dart import DARTProvider
 from .irishrail import IrishRailProvider
 from .tpg import TPGProvider
+from .vmv import VMVProvider
+from .gvh import GVHProvider
+from .nahsh import NAHSHProvider
+from .insa import INSAProvider
+from .vmt import VMTProvider
+from .saarvv import SaarVVProvider
+from .vbn_hafas import VBNHafasProvider
+from .nvv import NVVProvider
+from .vos import VOSProvider
+from .vsn import VSNProvider
+from .vao import VAOProvider
+from .trimet import TriMetProvider
+from .irail import IRailProvider
+from .sl import SLProvider
+from .ttc import TTCProvider
+from .hongkong import HongKongProvider
+from .wienerlinien import WienerLinienProvider
+from .tfl import TfLProvider
+from .tfnsw import TfNSWProvider
+from .digitransit import DigitransitProvider
+from .golemio import GolemioProvider
 
 _PROVIDER_REGISTRY: Dict[str, Type[BaseProvider]] = {}
 
@@ -152,7 +192,6 @@ register_provider(PROVIDER_TRANSITOUS, TransitousProvider)
 register_provider(PROVIDER_DB, DBProvider)
 register_provider(PROVIDER_VBN_OTP, VBNOTPProvider)
 register_provider(PROVIDER_VBN_TRIAS, VBNTriasProvider)
-register_provider(PROVIDER_OPT, OPTProvider)
 register_provider(PROVIDER_OTP_CUSTOM, OTPCustomProvider)
 register_provider(PROVIDER_NATIONAL_RAIL, NationalRailProvider)
 register_provider(PROVIDER_REJSEPLANEN, RejseplanenProvider)
@@ -163,4 +202,25 @@ register_provider(PROVIDER_BART_US, BARTProvider)
 register_provider(PROVIDER_DART_US, DARTProvider)
 register_provider(PROVIDER_IRISHRAIL_IE, IrishRailProvider)
 register_provider(PROVIDER_TPG_CH, TPGProvider)
+register_provider(PROVIDER_VMV, VMVProvider)
+register_provider(PROVIDER_GVH, GVHProvider)
+register_provider(PROVIDER_NAHSH, NAHSHProvider)
+register_provider(PROVIDER_INSA, INSAProvider)
+register_provider(PROVIDER_VMT, VMTProvider)
+register_provider(PROVIDER_SAARVV, SaarVVProvider)
+register_provider(PROVIDER_VBN_HAFAS, VBNHafasProvider)
+register_provider(PROVIDER_NVV, NVVProvider)
+register_provider(PROVIDER_VOS, VOSProvider)
+register_provider(PROVIDER_VSN, VSNProvider)
+register_provider(PROVIDER_VAO_AT, VAOProvider)
+register_provider(PROVIDER_TRIMET_US, TriMetProvider)
+register_provider(PROVIDER_IRAIL_BE, IRailProvider)
+register_provider(PROVIDER_SL_SE, SLProvider)
+register_provider(PROVIDER_TTC_CA, TTCProvider)
+register_provider(PROVIDER_HONGKONG, HongKongProvider)
+register_provider(PROVIDER_WIENERLINIEN, WienerLinienProvider)
+register_provider(PROVIDER_TFL, TfLProvider)
+register_provider(PROVIDER_TFNSW, TfNSWProvider)
+register_provider(PROVIDER_DIGITRANSIT, DigitransitProvider)
+register_provider(PROVIDER_GOLEMIO, GolemioProvider)
 register_provider(PROVIDER_HVV_GTI, HVVGTIProvider)

python_openpublictransport-0.3.0/src/openpublictransport/providers/db.py

@@ -0,0 +1,69 @@
+"""Deutsche Bahn provider implementation.
+
+Served through Transitous (MOTIS 2, api.transitous.org), which carries the
+nationwide DELFI timetable with DB real-time data. No API key required.
+
+The provider used to talk to the community proxy v6.db.transport.rest, which
+has been unavailable since autumn 2026. Entries created back then store a
+numeric station number (IBNR) as stop id; those are resolved once by name to
+the matching Transitous stop.
+"""
+
+import logging
+from typing import Any, Dict, List, Optional
+
+from ..const import PROVIDER_DB
+from .transitous import TransitousProvider
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class DBProvider(TransitousProvider):
+    """Deutsche Bahn (Germany-wide) via Transitous."""
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self._legacy_ids: Dict[str, str] = {}
+
+    @property
+    def provider_id(self) -> str:
+        return PROVIDER_DB
+
+    @property
+    def provider_name(self) -> str:
+        return "DB (Deutsche Bahn)"
+
+    def get_timezone(self) -> str:
+        return "Europe/Berlin"
+
+    async def search_stops(self, search_term: str) -> List[Dict[str, Any]]:
+        """Transitous searches worldwide; keep the German stops."""
+        stops = await super().search_stops(search_term)
+        german = [stop for stop in stops if stop.get("country") in (None, "", "DE")]
+        return german or stops
+
+    async def fetch_departures(
+        self,
+        station_id: Optional[str],
+        place_dm: str,
+        name_dm: str,
+        departures_limit: int,
+    ) -> Optional[Dict[str, Any]]:
+        if station_id and station_id.isdigit():
+            station_id = await self._resolve_legacy_id(station_id, name_dm or place_dm)
+        return await super().fetch_departures(station_id, place_dm, name_dm, departures_limit)
+
+    async def _resolve_legacy_id(self, ibnr: str, name: str) -> Optional[str]:
+        """Map a v6.db.transport.rest station number to a Transitous stop id."""
+        if ibnr in self._legacy_ids:
+            return self._legacy_ids[ibnr]
+        if not name:
+            _LOGGER.warning("DB: cannot resolve legacy station %s without a stop name", ibnr)
+            return None
+        stops = await self.search_stops(name)
+        if not stops:
+            _LOGGER.warning("DB: no Transitous stop found for legacy station %s (%s)", ibnr, name)
+            return None
+        self._legacy_ids[ibnr] = stops[0]["id"]
+        _LOGGER.debug("DB: legacy station %s (%s) resolved to %s", ibnr, name, stops[0]["id"])
+        return stops[0]["id"]

python_openpublictransport-0.3.0/src/openpublictransport/providers/digitransit.py

@@ -0,0 +1,102 @@
+"""Digitransit (Finland) provider — OpenTripPlanner 2 GraphQL.
+
+Requires a free subscription key from https://portal-api.digitransit.fi/,
+sent as the ``digitransit-subscription-key`` header.
+
+Default router is ``finland`` (all of Finland, incl. HSL Helsinki, Tampere,
+Turku, Oulu, VR long-distance trains). Regional routers can be selected via
+``custom_url``: either the full GraphQL URL or one of the shorthands
+``"finland"``, ``"hsl"`` (Helsinki region) and ``"waltti"`` (Waltti cities).
+
+Stop ids are GTFS ids (``HSL:1020453``); stops that share a parent station or
+lie close together with the same name are combined with ``|`` like the other
+OTP2 providers.
+"""
+
+import logging
+from typing import Any, Dict, List, Optional
+
+from .otp import OTPProvider, _smart_title
+from ..const import PROVIDER_DIGITRANSIT
+
+_LOGGER = logging.getLogger(__name__)
+
+
+ROUTER_URLS: Dict[str, str] = {
+    "finland": "https://api.digitransit.fi/routing/v2/finland/gtfs/v1",
+    "hsl": "https://api.digitransit.fi/routing/v2/hsl/gtfs/v1",
+    "waltti": "https://api.digitransit.fi/routing/v2/waltti/gtfs/v1",
+}
+
+MODE_MAPPING: Dict[str, str] = {
+    "BUS": "bus",
+    "COACH": "bus",
+    "TROLLEYBUS": "bus",
+    "RAIL": "train",
+    "TRAM": "tram",
+    "SUBWAY": "subway",
+    "FERRY": "ferry",
+    "FUNICULAR": "train",
+    "GONDOLA": "tram",
+    "CABLE_CAR": "tram",
+}
+
+
+class DigitransitProvider(OTPProvider):
+    """Digitransit Finland (HSL, Waltti, VR …)."""
+
+    otp_base_url: str = ROUTER_URLS["finland"]
+    geocode_countries: str = "fi"
+
+    @property
+    def provider_id(self) -> str:
+        return PROVIDER_DIGITRANSIT
+
+    @property
+    def provider_name(self) -> str:
+        return "Digitransit (Finnland)"
+
+    @property
+    def requires_api_key(self) -> bool:
+        return True
+
+    def get_timezone(self) -> str:
+        return "Europe/Helsinki"
+
+    def get_mode_mapping(self) -> Dict[str, str]:
+        return MODE_MAPPING
+
+    @property
+    def graphql_url(self) -> str:
+        custom = (self.custom_url or "").strip()
+        if custom:
+            return ROUTER_URLS.get(custom.lower(), custom.rstrip("/"))
+        return self.otp_base_url
+
+    def _auth_headers(self) -> Dict[str, str]:
+        headers = {"Accept": "application/json", "Content-Type": "application/json"}
+        if self.api_key:
+            headers["digitransit-subscription-key"] = self.api_key
+        return headers
+
+    async def _graphql(self, query: str) -> Optional[Dict[str, Any]]:
+        # Digitransit's endpoint *is* the GraphQL URL (no /index/graphql suffix).
+        return await self._request(
+            "post",
+            self.graphql_url,
+            json={"query": query},
+            headers=self._auth_headers(),
+            timeout=15,
+        )
+
+    async def search_stops(self, search_term: str) -> List[Dict[str, Any]]:
+        """Search by stop name; no German city-prefix / Nominatim fallbacks."""
+        term = search_term.strip()
+        if not term:
+            return []
+        smart = _smart_title(term)
+        for candidate in dict.fromkeys([term, smart]):
+            raw = await self._search_one(candidate)
+            if raw:
+                return self._group_by_name(raw)[:20]
+        return []

{python_openpublictransport-0.2.0 → python_openpublictransport-0.3.0}/src/openpublictransport/providers/efa_base.py

@@ -122,7 +122,7 @@ class EFABaseProvider(BaseProvider):
         """Fetch departure data from EFA API."""
         if station_id:
             params = (
-                f"outputFormat=RapidJSON&"
+                f"outputFormat=rapidJSON&"
                 f"stateless=1&"
                 f"type_dm=any&"
                 f"name_dm={station_id}&"
@@ -132,7 +132,7 @@ class EFABaseProvider(BaseProvider):
             )
         else:
             params = (
-                f"outputFormat=RapidJSON&"
+                f"outputFormat=rapidJSON&"
                 f"place_dm={place_dm}&"
                 f"type_dm=stop&"
                 f"name_dm={name_dm}&"
@@ -199,7 +199,7 @@ class EFABaseProvider(BaseProvider):
             stop_name = parts[0].strip()
             place_name = parts[1].strip()
             params = (
-                f"outputFormat=RapidJSON&"
+                f"outputFormat=rapidJSON&"
                 f"locationServerActive=1&"
                 f"type_sf=any&"
                 f"name_sf={quote(stop_name, safe='')}&"
@@ -208,7 +208,7 @@ class EFABaseProvider(BaseProvider):
             )
         else:
             params = (
-                f"outputFormat=RapidJSON&"
+                f"outputFormat=rapidJSON&"
                 f"locationServerActive=1&"
                 f"type_sf=stop&"
                 f"name_sf={quote(search_term, safe='')}&"
@@ -218,9 +218,10 @@ class EFABaseProvider(BaseProvider):
         url = f"{self.sf_base_url}?{params}"
         name = self.provider_name
 
-        # content_type=None: some deployments (VGN) send RapidJSON payloads with
-        # a "text/xml;;charset=utf-8" header (issue #79).
-        data = await self._request("get", url, timeout=10)
+        # Same User-Agent as the departure request: some EFA hosts throttle the
+        # bare aiohttp default (VRR answered it with HTTP 429).
+        headers = {"User-Agent": f"Mozilla/5.0 (compatible; OpenPublicTransport {self.provider_id.upper()})"}
+        data = await self._request("get", url, headers=headers, retries=2, timeout=10)
 
         if not isinstance(data, dict):
             raise ApiResponseError(f"{name}: API returned {type(data).__name__} instead of an object")

python_openpublictransport-0.3.0/src/openpublictransport/providers/golemio.py

@@ -0,0 +1,251 @@
+"""Golemio PID (Prague Integrated Transport) provider.
+
+Departures come from the Golemio API ``/v2/pid/departureboards`` and require a
+free key (https://api.golemio.cz/api-keys/), sent as the ``x-access-token``
+header.
+
+Golemio has no fuzzy stop search, so stop search uses the public PID stop list
+(https://data.pid.cz/stops/json/stops.json, no key, ~1.6 MB gzipped),
+downloaded once per provider instance and filtered locally.
+
+Station ids are ASW node numbers (``1072`` = Můstek): a node groups all
+platforms of a stop incl. metro and train stations. Also accepted: a single
+ASW stop ``1072/101`` / ``1072_101`` or a GTFS stop id ``U1072Z101P``; several
+ids may be combined with ``|``.
+"""
+
+import logging
+import re
+import unicodedata
+from datetime import datetime
+from typing import Any, Dict, List, Optional, Tuple, Union
+from zoneinfo import ZoneInfo
+
+from ..exceptions import ApiResponseError, AuthenticationError
+from ..models import UnifiedDeparture
+from .base import BaseProvider
+from ..const import PROVIDER_GOLEMIO
+
+_LOGGER = logging.getLogger(__name__)
+
+
+DEPARTURES_URL = "https://api.golemio.cz/v2/pid/departureboards"
+STOPS_URL = "https://data.pid.cz/stops/json/stops.json"
+
+# GTFS route types as used by PID.
+ROUTE_TYPES: Dict[Any, str] = {
+    0: "tram",
+    1: "subway",
+    2: "train",
+    3: "bus",
+    4: "ferry",
+    7: "train",  # funicular (Petřín)
+    11: "bus",  # trolleybus
+}
+
+_GTFS_ID_RE = re.compile(r"^U\d+[ZN]\d+", re.IGNORECASE)
+
+
+def _normalize(text: str) -> str:
+    text = (text or "").casefold()
+    return "".join(c for c in unicodedata.normalize("NFKD", text) if not unicodedata.combining(c))
+
+
+def _parse_dt(value: Any) -> Optional[datetime]:
+    if not isinstance(value, str) or not value:
+        return None
+    try:
+        return datetime.fromisoformat(value)
+    except ValueError:
+        return None
+
+
+def departure_params(station_id: str, limit: int) -> List[Tuple[str, str]]:
+    """Build the departureboards query for one or more ``|``-separated ids."""
+    params: List[Tuple[str, str]] = []
+    for part in station_id.split("|"):
+        part = part.strip()
+        if not part:
+            continue
+        if _GTFS_ID_RE.match(part):
+            params.append(("ids[]", part))
+        else:
+            params.append(("aswIds[]", part.replace("/", "_")))
+    params += [
+        ("limit", str(limit)),
+        ("minutesBefore", "0"),
+        ("minutesAfter", "180"),
+        ("mode", "departures"),
+        ("order", "real"),
+        ("skip[]", "canceled"),
+    ]
+    return params
+
+
+class GolemioProvider(BaseProvider):
+    """PID Prague via Golemio."""
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self._stops: Optional[List[Dict[str, str]]] = None
+
+    @property
+    def provider_id(self) -> str:
+        return PROVIDER_GOLEMIO
+
+    @property
+    def provider_name(self) -> str:
+        return "PID (Praha)"
+
+    @property
+    def requires_api_key(self) -> bool:
+        return True
+
+    def get_timezone(self) -> str:
+        return "Europe/Prague"
+
+    def get_transport_type_mapping(self) -> Dict[Any, str]:
+        return ROUTE_TYPES
+
+    def _headers(self) -> Dict[str, str]:
+        if not self.api_key:
+            raise AuthenticationError(self.provider_name, 401, message=f"{self.provider_name}: API key required")
+        return {"x-access-token": self.api_key, "Accept": "application/json"}
+
+    async def fetch_departures(
+        self,
+        station_id: Optional[str],
+        place_dm: str,
+        name_dm: str,
+        departures_limit: int,
+    ) -> Optional[Dict[str, Any]]:
+        if station_id:
+            params = departure_params(station_id, departures_limit)
+        elif name_dm:
+            # Exact (case-sensitive) stop name, as Golemio's names[] requires.
+            params = [("names[]", name_dm), ("limit", str(departures_limit)), ("skip[]", "canceled")]
+        else:
+            return None
+
+        data = await self._request(
+            "get", DEPARTURES_URL, params=params, headers=self._headers(), timeout=15, retries=2
+        )
+        if not isinstance(data, dict):
+            raise ApiResponseError(f"{self.provider_name}: API returned {type(data).__name__} instead of an object")
+        return {"stopEvents": self.events_from_board(data)[:departures_limit]}
+
+    @staticmethod
+    def events_from_board(data: Dict[str, Any]) -> List[Dict[str, Any]]:
+        """Attach the board's infotexts to every departure."""
+        notices: List[str] = []
+        for info in data.get("infotexts") or []:
+            if isinstance(info, dict):
+                text = " ".join((info.get("text") or info.get("text_en") or "").split())
+                if text and text not in notices:
+                    notices.append(text)
+        events = []
+        for dep in data.get("departures") or []:
+            if isinstance(dep, dict):
+                events.append({**dep, "_notices": notices or None})
+        return events
+
+    def parse_departure(
+        self, stop: Dict[str, Any], tz: Union[ZoneInfo, Any], now: datetime
+    ) -> Optional[UnifiedDeparture]:
+        try:
+            times = stop.get("departure_timestamp") or {}
+            scheduled = _parse_dt(times.get("scheduled"))
+            if scheduled is None:
+                return None
+            predicted = _parse_dt(times.get("predicted"))
+            delay_info = stop.get("delay") or {}
+            is_realtime = bool(delay_info.get("is_available"))
+
+            planned_local = scheduled.astimezone(tz)
+            dep_local = predicted.astimezone(tz) if predicted else planned_local
+
+            if is_realtime and delay_info.get("minutes") is not None:
+                delay = int(delay_info["minutes"])
+            else:
+                delay = round((dep_local - planned_local).total_seconds() / 60)
+            minutes_until = max(0, int((dep_local - now).total_seconds() / 60))
+
+            route = stop.get("route") or {}
+            trip = stop.get("trip") or {}
+            stop_ref = stop.get("stop") or {}
+
+            transport_type = ROUTE_TYPES.get(route.get("type"), "unknown")
+            notices = list(stop.get("_notices") or [])
+            if trip.get("is_canceled"):
+                notices.insert(0, "Spoj odřeknut / Trip cancelled")
+
+            return UnifiedDeparture(
+                line=str(route.get("short_name") or ""),
+                destination=trip.get("headsign") or "Unknown",
+                departure_time=dep_local.strftime("%H:%M"),
+                planned_time=planned_local.strftime("%H:%M"),
+                delay=delay,
+                platform=stop_ref.get("platform_code") or None,
+                transportation_type=transport_type,
+                is_realtime=is_realtime,
+                minutes_until_departure=minutes_until,
+                departure_time_obj=dep_local,
+                description=trip.get("short_name") or None,
+                agency="PID",
+                notices=notices or None,
+            )
+        except Exception as exc:  # noqa: BLE001
+            _LOGGER.debug("Error parsing Golemio departure: %s", exc)
+            return None
+
+    @staticmethod
+    def parse_stop_groups(data: Dict[str, Any]) -> List[Dict[str, str]]:
+        """Reduce stops.json to one entry per ASW node."""
+        result = []
+        seen: set = set()
+        for group in data.get("stopGroups") or []:
+            if not isinstance(group, dict) or group.get("node") is None:
+                continue
+            node = str(group["node"])
+            if node in seen:
+                continue
+            seen.add(node)
+            result.append(
+                {
+                    "id": node,
+                    "name": group.get("uniqueName") or group.get("name") or "",
+                    "place": group.get("municipality") or "",
+                }
+            )
+        return result
+
+    async def _load_stops(self) -> List[Dict[str, str]]:
+        if self._stops is None:
+            data = await self._request("get", STOPS_URL, timeout=30, retries=2)
+            if not isinstance(data, dict):
+                raise ApiResponseError(f"{self.provider_name}: stop list is {type(data).__name__}, expected an object")
+            self._stops = self.parse_stop_groups(data)
+        return self._stops
+
+    @staticmethod
+    def filter_stops(stops: List[Dict[str, str]], search_term: str, limit: int = 20) -> List[Dict[str, Any]]:
+        tokens = _normalize(search_term).replace(",", " ").split()
+        if not tokens:
+            return []
+        term = " ".join(tokens)
+        scored = []
+        for st in stops:
+            if not all(t in _normalize(f"{st['name']} {st['place']}") for t in tokens):
+                continue
+            name = _normalize(st["name"])
+            score = 0 if name == term else 1 if name.startswith(term) else 2
+            prague = 0 if st["place"] == "Praha" else 1
+            scored.append((score, prague, len(name), st["name"], st))
+        scored.sort(key=lambda x: x[:4])
+        return [
+            {"id": st["id"], "name": st["name"], "place": st["place"], "area_type": "stop"}
+            for *_, st in scored[:limit]
+        ]
+
+    async def search_stops(self, search_term: str) -> List[Dict[str, Any]]:
+        return self.filter_stops(await self._load_stops(), search_term)