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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-openpublictransport
-Version: 0.1.17
+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.1.17 → python_openpublictransport-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-openpublictransport"
-version = "0.1.17"
+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.1.17 → python_openpublictransport-0.3.0}/src/openpublictransport/__init__.py

@@ -1,6 +1,13 @@
 """python-openpublictransport — public transport API library."""
 
-from .exceptions import AuthenticationError
+from .exceptions import (
+    ApiConnectionError,
+    ApiError,
+    ApiResponseError,
+    ApiTimeoutError,
+    AuthenticationError,
+    OpenPublicTransportError,
+)
 from .providers import get_all_provider_ids, get_provider, get_provider_class, register_provider
 
 __all__ = [
@@ -8,5 +15,10 @@ __all__ = [
     "get_provider_class",
     "get_all_provider_ids",
     "register_provider",
+    "OpenPublicTransportError",
+    "ApiError",
+    "ApiConnectionError",
+    "ApiTimeoutError",
+    "ApiResponseError",
     "AuthenticationError",
 ]

{python_openpublictransport-0.1.17 → 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.3.0/src/openpublictransport/exceptions.py

@@ -0,0 +1,81 @@
+"""Exceptions for python-openpublictransport.
+
+Every failure raised by this library derives from :class:`OpenPublicTransportError`.
+Callers can therefore catch the whole family with a single ``except`` clause, or
+discriminate on the concrete type to tell a server-side outage apart from a
+network problem or an empty result.
+
+Empty results are *not* errors: ``search_stops()`` returns ``[]`` and
+``fetch_departures()`` returns ``None`` only when the provider genuinely had no
+data to give.
+"""
+
+from typing import Optional
+
+
+class OpenPublicTransportError(Exception):
+    """Base class for every error raised by this library."""
+
+
+class ApiError(OpenPublicTransportError):
+    """Raised when a provider API answers with a non-200 HTTP status.
+
+    The HTTP status is available as :attr:`status` so callers can report it to
+    the user instead of silently treating the failure as "no results".
+    :attr:`body` holds a truncated copy of the error response, which is often
+    the only place a provider explains what it disliked.
+    """
+
+    def __init__(
+        self,
+        provider: str,
+        status: int,
+        message: Optional[str] = None,
+        body: Optional[str] = None,
+    ) -> None:
+        self.provider = provider
+        self.status = status
+        self.body = body
+        if message is None:
+            message = f"{provider}: API returned HTTP {status}"
+            if body:
+                message = f"{message} — {body}"
+        super().__init__(message)
+
+
+class ApiConnectionError(OpenPublicTransportError):
+    """Raised when the provider API cannot be reached (DNS, TCP or TLS failure)."""
+
+
+class ApiTimeoutError(ApiConnectionError):
+    """Raised when the provider API does not answer within the timeout."""
+
+
+class ApiResponseError(OpenPublicTransportError):
+    """Raised when a 200 response carries a payload that cannot be used.
+
+    Covers undecodable JSON/XML as well as a well-formed body whose shape does
+    not match what the provider protocol requires.
+    """
+
+
+class AuthenticationError(ApiError):
+    """Raised when API authentication fails (HTTP 401 or 403).
+
+    Signals that the configured API key is invalid or expired.
+    Callers should prompt the user to re-enter credentials rather than retrying.
+    """
+
+    def __init__(
+        self,
+        provider: str,
+        status: int = 401,
+        message: Optional[str] = None,
+        body: Optional[str] = None,
+    ) -> None:
+        super().__init__(
+            provider,
+            status,
+            message or f"{provider}: authentication failed (HTTP {status}) — check the API key",
+            body=body,
+        )

{python_openpublictransport-0.1.17 → 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/base.py

@@ -0,0 +1,199 @@
+"""Base class for all public transport providers."""
+
+import asyncio
+import logging
+
+import aiohttp
+from abc import ABC, abstractmethod
+from datetime import datetime
+from typing import Any, Dict, List, Optional, Union
+from zoneinfo import ZoneInfo
+
+from ..exceptions import (
+    ApiConnectionError,
+    ApiError,
+    ApiResponseError,
+    ApiTimeoutError,
+    AuthenticationError,
+)
+from ..models import UnifiedDeparture
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class BaseProvider(ABC):
+    """Abstract base class for all public transport providers."""
+
+    def __init__(
+        self,
+        session: aiohttp.ClientSession,
+        api_key: Optional[str] = None,
+        api_key_secondary: Optional[str] = None,
+        custom_url: Optional[str] = None,
+    ):
+        self.session = session
+        self.api_key = api_key
+        self.api_key_secondary = api_key_secondary
+        self.custom_url = custom_url
+
+    async def _request(
+        self,
+        method: str,
+        url: str,
+        *,
+        retries: int = 1,
+        timeout: int = 10,
+        response_format: str = "json",
+        json_content_type: Optional[str] = None,
+        **kwargs: Any,
+    ) -> Any:
+        """Perform an HTTP request, returning the decoded payload or raising.
+
+        This is the single place where HTTP status codes are turned into
+        exceptions. Providers must not swallow the result: an empty list or
+        ``None`` returned by a provider means "no data", never "request failed".
+
+        Args:
+            method: ``"get"`` or ``"post"``.
+            url: Absolute request URL.
+            retries: Total number of attempts. Only 5xx responses, timeouts and
+                connection errors are retried, with ``2 ** attempt`` backoff.
+                4xx responses fail immediately — retrying a bad key or a wrong
+                endpoint only delays the error the user needs to see.
+            timeout: Total request timeout in seconds.
+            response_format: ``"json"``, ``"text"`` or ``"bytes"``.
+            json_content_type: Passed to ``response.json()``. The default
+                ``None`` disables aiohttp's strict content-type check, because
+                some EFA deployments send RapidJSON with an XML header (#79).
+            **kwargs: Forwarded to the aiohttp session method (``params``,
+                ``headers``, ``data``, ``json``, ...).
+
+        Returns:
+            The decoded payload, or ``None`` for an empty 204 response.
+
+        Raises:
+            AuthenticationError: HTTP 401 or 403. Never retried.
+            ApiError: Any other non-2xx status, carrying ``.status``.
+            ApiTimeoutError: The request timed out on every attempt.
+            ApiConnectionError: The provider could not be reached.
+            ApiResponseError: A 2xx response whose body could not be decoded.
+        """
+        request = getattr(self.session, method.lower())
+        name = self.provider_name
+        last_error: Optional[Exception] = None
+
+        for attempt in range(1, retries + 1):
+            try:
+                async with request(url, timeout=aiohttp.ClientTimeout(total=timeout), **kwargs) as response:
+                    status = response.status
+
+                    if status in (401, 403):
+                        raise AuthenticationError(name, status, body=await self._error_body(response))
+
+                    if status >= 500:
+                        last_error = ApiError(name, status, body=await self._error_body(response))
+                    elif status >= 400:
+                        raise ApiError(name, status, body=await self._error_body(response))
+                    elif status == 204:
+                        return None
+                    else:
+                        return await self._decode_response(response, response_format, json_content_type)
+
+            except asyncio.TimeoutError as exc:
+                last_error = ApiTimeoutError(f"{name}: request timed out after {timeout}s")
+                last_error.__cause__ = exc
+            except aiohttp.ClientError as exc:
+                last_error = ApiConnectionError(f"{name}: connection failed ({exc})")
+                last_error.__cause__ = exc
+
+            if attempt < retries:
+                _LOGGER.debug("%s: attempt %s/%s failed (%s), retrying", name, attempt, retries, last_error)
+                await asyncio.sleep(2**attempt)
+
+        raise last_error if last_error else ApiConnectionError(f"{name}: request failed")
+
+    @staticmethod
+    async def _error_body(response: Any, limit: int = 300) -> Optional[str]:
+        """Return a truncated error body, or None if it cannot be read.
+
+        Providers often explain a rejection only in the body (a SOAP fault, a
+        JSON ``errorText``), so it is worth carrying into the exception.
+        """
+        try:
+            text = (await response.text() or "").strip()
+        except Exception:  # noqa: BLE001 — diagnostics must never mask the real error
+            return None
+        if not text:
+            return None
+        return text[:limit] + ("…" if len(text) > limit else "")
+
+    async def _decode_response(
+        self,
+        response: Any,
+        response_format: str,
+        json_content_type: Optional[str],
+    ) -> Any:
+        """Decode a successful response, raising ApiResponseError on bad payloads."""
+        try:
+            if response_format == "json":
+                return await response.json(content_type=json_content_type)
+            if response_format == "text":
+                return await response.text()
+            if response_format == "bytes":
+                return await response.read()
+        except (ValueError, aiohttp.ClientError) as exc:
+            raise ApiResponseError(f"{self.provider_name}: could not decode response ({exc})") from exc
+
+        raise ValueError(f"Unknown response_format: {response_format}")
+
+    @property
+    @abstractmethod
+    def provider_id(self) -> str:
+        """Return the provider identifier (e.g., 'vrr', 'kvv')."""
+        pass
+
+    @property
+    @abstractmethod
+    def provider_name(self) -> str:
+        """Return the human-readable provider name."""
+        pass
+
+    @property
+    def requires_api_key(self) -> bool:
+        """Return True if this provider requires an API key."""
+        return False
+
+    @abstractmethod
+    async def fetch_departures(
+        self,
+        station_id: Optional[str],
+        place_dm: str,
+        name_dm: str,
+        departures_limit: int,
+    ) -> Optional[Dict[str, Any]]:
+        """Fetch departure data from the provider's API."""
+        pass
+
+    @abstractmethod
+    def parse_departure(
+        self, stop: Dict[str, Any], tz: Union[ZoneInfo, Any], now: datetime
+    ) -> Optional[UnifiedDeparture]:
+        """Parse a single departure from the provider's API response."""
+        pass
+
+    @abstractmethod
+    async def search_stops(self, search_term: str) -> List[Dict[str, Any]]:
+        """Search for stops/stations."""
+        pass
+
+    def get_timezone(self) -> str:
+        """Return the timezone for this provider (e.g., 'Europe/Berlin')."""
+        return "Europe/Berlin"
+
+    def get_transport_type_mapping(self) -> Dict[Any, str]:
+        """Return the transportation type mapping for this provider."""
+        return {}
+
+    async def cleanup(self) -> None:
+        """Cleanup provider resources."""
+        pass

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 []