python-openpublictransport 0.1.15__tar.gz → 0.1.16__tar.gz

{python_openpublictransport-0.1.15 → python_openpublictransport-0.1.16}/PKG-INFO

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

{python_openpublictransport-0.1.15 → python_openpublictransport-0.1.16}/pyproject.toml

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

{python_openpublictransport-0.1.15 → python_openpublictransport-0.1.16}/src/openpublictransport/const.py

@@ -4,6 +4,7 @@
 PROVIDER_VRR = "vrr"
 PROVIDER_KVV = "kvv"
 PROVIDER_HVV = "hvv"
+PROVIDER_HVV_GTI = "hvv_gti"  # HVV via the official Geofox GTI API (credentials required)
 PROVIDER_BVG = "bvg"
 PROVIDER_MVV = "mvv"
 PROVIDER_VVS = "vvs"

{python_openpublictransport-0.1.15 → python_openpublictransport-0.1.16}/src/openpublictransport/providers/__init__.py

@@ -11,6 +11,7 @@ from ..const import (
     PROVIDER_DB,
     PROVIDER_DING,
     PROVIDER_HVV,
+    PROVIDER_HVV_GTI,
     PROVIDER_KVV,
     PROVIDER_MVV,
     PROVIDER_NTA_IE,
@@ -51,6 +52,7 @@ 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
 from .mvv import MVVProvider
 from .nta import NTAProvider
@@ -161,3 +163,4 @@ 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_HVV_GTI, HVVGTIProvider)

python_openpublictransport-0.1.16/src/openpublictransport/providers/hvv_gti.py

@@ -0,0 +1,358 @@
+"""HVV via the official Geofox Thin Interface (GTI).
+
+The `hvv` provider talks to the public EFA endpoint. This one uses HOCHBAHN's
+official API on behalf of the HVV, which carries real-time delays, cancellations
+and platform changes that EFA does not expose.
+
+Credentials are free but must be requested by email from api@hochbahn.de; the
+API is documented at https://gti.geofox.de/html/GTIHandbuch_p.html.
+
+Requested for https://github.com/NerdySoftPaw/openpublictransport/issues/61.
+"""
+
+import base64
+import hashlib
+import hmac
+import json
+import logging
+from datetime import datetime, timedelta
+from typing import Any, Dict, List, Optional, Union
+from zoneinfo import ZoneInfo
+
+import aiohttp
+
+from ..const import PROVIDER_HVV_GTI
+from ..exceptions import AuthenticationError
+from ..models import UnifiedDeparture
+from .base import BaseProvider
+
+_LOGGER = logging.getLogger(__name__)
+
+GTI_BASE_URL = "https://gti.geofox.de/gti/public"
+
+# The API version the request bodies below are written against. The server
+# tailors its response to this number, so it is pinned rather than left to the
+# server default (which is the long-obsolete version 1).
+GTI_API_VERSION = 63
+
+# A line's type carries a granular value (`shortInfo`, and sometimes a granular
+# `simpleType`) plus a coarse `simpleType`. The granular one is authoritative;
+# the coarse one flattens U-Bahn, S-Bahn and AKN all into TRAIN, so it is only
+# consulted after the line name has had a chance to disambiguate.
+_GRANULAR_TYPE_MAP = {
+    "UBAHN": "subway",
+    "U": "subway",
+    "U-BAHN": "subway",
+    "SBAHN": "train",
+    "S": "train",
+    "S-BAHN": "train",
+    "AKN": "train",
+    "A": "train",
+    "RBAHN": "train",
+    "R": "train",
+    "FERNBAHN": "train",
+    "ZUG": "train",
+    "STADTBUS": "bus",
+    "METROBUS": "bus",
+    "SCHNELLBUS": "bus",
+    "NACHTBUS": "bus",
+    "XPRESSBUS": "bus",
+    "EILBUS": "bus",
+    "FAEHRE": "ferry",
+    "FÄHRE": "ferry",
+    "AST": "taxi",
+}
+
+_COARSE_TYPE_MAP = {
+    "BUS": "bus",
+    "TRAIN": "train",
+    "SHIP": "ferry",
+}
+
+
+def sign_request(password: str, body: bytes) -> str:
+    """Return the geofox-auth-signature for a request body.
+
+    HMAC-SHA1 over the UTF-8 request body, keyed with the password, Base64
+    encoded — GTI handbook §3 "Authentifikation".
+    """
+    digest = hmac.new(password.encode("utf-8"), body, hashlib.sha1).digest()
+    return base64.b64encode(digest).decode("ascii")
+
+
+def _transport_type(line: Dict[str, Any]) -> str:
+    """Map a GTI line to a unified transportation type."""
+    line_type = line.get("type") if isinstance(line.get("type"), dict) else {}
+    short_info = str(line_type.get("shortInfo") or "").strip().upper()
+    simple_type = str(line_type.get("simpleType") or "").strip().upper()
+
+    for value in (short_info, simple_type):
+        if value in _GRANULAR_TYPE_MAP:
+            return _GRANULAR_TYPE_MAP[value]
+
+    # Only the coarse type is left, which lumps U-Bahn, S-Bahn and AKN together
+    # under TRAIN. Hamburg's line names are unambiguous, so use them first.
+    name = str(line.get("name") or "").strip().upper()
+    if len(name) > 1 and name[1].isdigit():
+        if name[0] == "U":
+            return "subway"
+        if name[0] in ("S", "A", "R"):
+            return "train"
+
+    if simple_type in _COARSE_TYPE_MAP:
+        return _COARSE_TYPE_MAP[simple_type]
+
+    _LOGGER.debug("HVV GTI: unmapped line type %s for line %r", line_type, line.get("name"))
+    return "unknown"
+
+
+class HVVGTIProvider(BaseProvider):
+    """HVV via the official Geofox GTI API (real-time)."""
+
+    @property
+    def provider_id(self) -> str:
+        return PROVIDER_HVV_GTI
+
+    @property
+    def provider_name(self) -> str:
+        return "HVV Geofox GTI (Hamburg)"
+
+    @property
+    def requires_api_key(self) -> bool:
+        return True
+
+    def get_timezone(self) -> str:
+        return "Europe/Berlin"
+
+    # ── transport ────────────────────────────────────────────────────────────
+
+    async def _post(self, method: str, payload: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+        """Call one GTI method, signing the exact bytes that are sent.
+
+        The signature covers the serialized body, so the body is serialized
+        once and handed to aiohttp as raw bytes — letting aiohttp re-serialize
+        it via ``json=`` could change the bytes and invalidate the signature.
+        """
+        if not self.api_key or not self.api_key_secondary:
+            _LOGGER.error("%s: username and password are required", self.provider_name)
+            raise AuthenticationError(f"{self.provider_name}: username and password are required")
+
+        body = json.dumps(
+            {"version": GTI_API_VERSION, "language": "de", **payload},
+            ensure_ascii=False,
+            separators=(",", ":"),
+        ).encode("utf-8")
+
+        headers = {
+            "geofox-auth-type": "HmacSHA1",
+            "geofox-auth-user": self.api_key,
+            "geofox-auth-signature": sign_request(self.api_key_secondary, body),
+            "Content-Type": "application/json;charset=UTF-8",
+            "Accept": "application/json",
+            "X-Platform": "web",
+        }
+
+        url = f"{GTI_BASE_URL}/{method}"
+        try:
+            async with self.session.post(
+                url, data=body, headers=headers, timeout=aiohttp.ClientTimeout(total=15)
+            ) as response:
+                if response.status in (401, 403):
+                    raise AuthenticationError(
+                        f"{self.provider_name}: authentication failed (HTTP {response.status}) — "
+                        "check the GTI username and password"
+                    )
+                if response.status != 200:
+                    _LOGGER.warning("%s: %s → HTTP %s", self.provider_name, method, response.status)
+                    return None
+
+                data = await response.json(content_type=None)
+        except AuthenticationError:
+            raise
+        except aiohttp.ClientError as exc:
+            _LOGGER.warning("%s: %s request failed: %s", self.provider_name, method, exc)
+            return None
+        except Exception as exc:
+            _LOGGER.warning("%s: %s error: %s", self.provider_name, method, exc)
+            return None
+
+        if not isinstance(data, dict):
+            _LOGGER.warning("%s: %s returned %s, expected an object", self.provider_name, method, type(data))
+            return None
+
+        return_code = data.get("returnCode")
+        if return_code != "OK":
+            # GTI signals a bad key with a return code rather than an HTTP status.
+            if return_code in ("ERROR_COMM", "ERROR_TEXT") and "auth" in str(data.get("errorDevInfo", "")).lower():
+                raise AuthenticationError(f"{self.provider_name}: {data.get('errorText') or return_code}")
+            _LOGGER.warning(
+                "%s: %s returned %s — %s (%s)",
+                self.provider_name,
+                method,
+                return_code,
+                data.get("errorText") or "no message",
+                data.get("errorDevInfo") or "",
+            )
+            return None
+
+        return data
+
+    # ── stop search ──────────────────────────────────────────────────────────
+
+    async def search_stops(self, search_term: str) -> List[Dict[str, Any]]:
+        """Search stations via the checkName method."""
+        data = await self._post(
+            "checkName",
+            {
+                "theName": {"name": search_term, "type": "STATION"},
+                "maxList": 25,
+                "coordinateType": "EPSG_4326",
+            },
+        )
+        if not data:
+            return []
+
+        stops = []
+        for result in data.get("results") or []:
+            if not isinstance(result, dict) or result.get("type") != "STATION" or not result.get("id"):
+                continue
+            stops.append(
+                {
+                    "id": result["id"],
+                    "name": result.get("name", ""),
+                    "place": result.get("city", ""),
+                    "area_type": "stop",
+                }
+            )
+        return stops
+
+    # ── departures ───────────────────────────────────────────────────────────
+
+    async def fetch_departures(
+        self,
+        station_id: Optional[str],
+        place_dm: str,
+        name_dm: str,
+        departures_limit: int,
+    ) -> Optional[Dict[str, Any]]:
+        """Fetch a departure board via the departureList method."""
+        if not station_id:
+            _LOGGER.warning("%s: a station ID is required", self.provider_name)
+            return None
+
+        now = datetime.now(ZoneInfo(self.get_timezone()))
+        data = await self._post(
+            "departureList",
+            {
+                "station": {"id": station_id, "type": "STATION"},
+                "time": {"date": now.strftime("%d.%m.%Y"), "time": now.strftime("%H:%M")},
+                "maxList": max(departures_limit, 5),
+                "maxTimeOffset": 200,
+                "useRealtime": True,
+                "returnFilters": False,
+                "coordinateType": "EPSG_4326",
+            },
+        )
+        if not data:
+            return None
+
+        # Departures are offsets from the board's own reference time, not
+        # absolute timestamps, so it has to be resolved here while we still
+        # have the response that produced them.
+        reference = self._reference_time(data.get("time"), now)
+
+        stop_events = []
+        for departure in data.get("departures") or []:
+            event = self._to_stop_event(departure, reference)
+            if event:
+                stop_events.append(event)
+
+        stop_events.sort(key=lambda event: event["estimated"])
+        return {"stopEvents": stop_events[:departures_limit]}
+
+    def _reference_time(self, gti_time: Any, fallback: datetime) -> datetime:
+        """Parse the response's GTITime, falling back to the request time."""
+        if isinstance(gti_time, dict) and gti_time.get("date") and gti_time.get("time"):
+            try:
+                return datetime.strptime(
+                    f"{gti_time['date']} {gti_time['time']}", "%d.%m.%Y %H:%M"
+                ).replace(tzinfo=ZoneInfo(self.get_timezone()))
+            except ValueError:
+                _LOGGER.debug("%s: unparseable reference time %s", self.provider_name, gti_time)
+        return fallback
+
+    def _to_stop_event(self, departure: Any, reference: datetime) -> Optional[Dict[str, Any]]:
+        """Normalise one GTI departure into this provider's stop-event shape."""
+        if not isinstance(departure, dict):
+            return None
+
+        line = departure.get("line") if isinstance(departure.get("line"), dict) else {}
+        time_offset = departure.get("timeOffset")
+        if not isinstance(time_offset, int):
+            _LOGGER.debug("%s: departure without a timeOffset: %s", self.provider_name, departure)
+            return None
+
+        # planned = board reference + timeOffset; the real-time deviation is a
+        # separate value in seconds on top (GTI handbook §2.4.2).
+        delay_seconds = departure.get("delay") if isinstance(departure.get("delay"), int) else 0
+        planned = reference + timedelta(minutes=time_offset)
+        estimated = planned + timedelta(seconds=delay_seconds)
+
+        platform = departure.get("realtimePlatform") or departure.get("platform") or ""
+        planned_platform = departure.get("platform") or ""
+
+        notices = []
+        for attribute in departure.get("attributes") or []:
+            if isinstance(attribute, dict):
+                text = attribute.get("value") or attribute.get("title") or ""
+                if text:
+                    notices.append(str(text).strip())
+        if departure.get("cancelled"):
+            notices.append("Fahrt fällt aus")
+        if departure.get("extra"):
+            notices.append("Verstärkerfahrt")
+
+        return {
+            "line": str(line.get("name") or ""),
+            "destination": str(line.get("direction") or "Unknown"),
+            "transportType": _transport_type(line),
+            "planned": planned,
+            "estimated": estimated,
+            "delaySeconds": delay_seconds,
+            "isRealtime": departure.get("delay") is not None,
+            "platform": str(platform),
+            "plannedPlatform": str(planned_platform),
+            "cancelled": bool(departure.get("cancelled")),
+            "notices": notices or None,
+        }
+
+    def parse_departure(
+        self, stop: Dict[str, Any], tz: Union[ZoneInfo, Any], now: datetime
+    ) -> Optional[UnifiedDeparture]:
+        """Build a UnifiedDeparture from a stop event produced above."""
+        try:
+            planned = stop["planned"].astimezone(tz)
+            estimated = stop["estimated"].astimezone(tz)
+
+            platform = stop.get("platform") or ""
+            planned_platform = stop.get("plannedPlatform") or ""
+            platform_changed = bool(platform and planned_platform and platform != planned_platform)
+
+            return UnifiedDeparture(
+                line=stop.get("line", ""),
+                destination=stop.get("destination", "Unknown"),
+                departure_time=estimated.strftime("%H:%M"),
+                planned_time=planned.strftime("%H:%M"),
+                delay=int(stop.get("delaySeconds", 0) / 60),
+                platform=platform,
+                transportation_type=stop.get("transportType", "unknown"),
+                is_realtime=bool(stop.get("isRealtime")),
+                minutes_until_departure=max(0, int((estimated - now).total_seconds() / 60)),
+                departure_time_obj=estimated,
+                notices=stop.get("notices"),
+                planned_platform=planned_platform if platform_changed else None,
+                platform_changed=platform_changed,
+            )
+        except Exception as exc:
+            _LOGGER.debug("%s parse_departure error: %s", self.provider_name, exc)
+            return None

{python_openpublictransport-0.1.15 → python_openpublictransport-0.1.16}/src/python_openpublictransport.egg-info/PKG-INFO

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

{python_openpublictransport-0.1.15 → python_openpublictransport-0.1.16}/src/python_openpublictransport.egg-info/SOURCES.txt

@@ -23,6 +23,7 @@ src/openpublictransport/providers/gtfsde.py
 src/openpublictransport/providers/hafas_base.py
 src/openpublictransport/providers/hafas_mgate_base.py
 src/openpublictransport/providers/hvv.py
+src/openpublictransport/providers/hvv_gti.py
 src/openpublictransport/providers/irishrail.py
 src/openpublictransport/providers/kvv.py
 src/openpublictransport/providers/mobiliteit_lu.py
@@ -60,6 +61,7 @@ tests/test_efa_platform.py
 tests/test_entur.py
 tests/test_hafas_base.py
 tests/test_hafas_mgate.py
+tests/test_hvv_gti.py
 tests/test_national_rail.py
 tests/test_national_rail_parse.py
 tests/test_national_rail_static.py

{python_openpublictransport-0.1.15 → python_openpublictransport-0.1.16}/tests/test_efa_platform.py

@@ -183,6 +183,8 @@ def test_normalize_platform():
     assert normalize_platform("Track 1") == "1"
     assert normalize_platform(None) == ""
     assert normalize_platform("") == ""
-    # A platform genuinely named "Gleis" keeps a usable value
-    assert normalize_platform("Gleis") == ""
     assert normalize_platform(3) == "3"
+    # A bare label with no identifier after it normalizes away to nothing.
+    # Harmless: an empty value never takes part in a platform_changed
+    # decision, which requires both sides to be non-empty.
+    assert normalize_platform("Gleis") == ""

python_openpublictransport-0.1.16/tests/test_hvv_gti.py

@@ -0,0 +1,360 @@
+"""Tests for the HVV Geofox GTI provider.
+
+The official HOCHBAHN/HVV API. Payloads follow the examples in the GTI handbook
+(https://gti.geofox.de/html/GTIHandbuch_p.html).
+See https://github.com/NerdySoftPaw/openpublictransport/issues/61.
+"""
+
+import base64
+import hashlib
+import hmac
+import json
+from datetime import datetime
+from types import SimpleNamespace
+from zoneinfo import ZoneInfo
+
+import pytest
+
+from openpublictransport.exceptions import AuthenticationError
+from openpublictransport.providers import get_provider
+from openpublictransport.providers.hvv_gti import HVVGTIProvider, sign_request
+
+TZ = ZoneInfo("Europe/Berlin")
+NOW = datetime(2026, 8, 1, 21, 28, tzinfo=TZ)
+
+# From the handbook's departureList example, extended with the real-time fields.
+DEPARTURE_LIST_RESPONSE = {
+    "returnCode": "OK",
+    "time": {"date": "01.08.2026", "time": "21:28"},
+    "departures": [
+        {
+            "line": {
+                "name": "476",
+                "direction": "Ahrensburg, Auestieg",
+                "type": {"simpleType": "BUS", "shortInfo": "Bus"},
+                "id": "VHH:476_VHH",
+            },
+            "timeOffset": 20,
+            "serviceId": 200023670,
+            "platform": "5",
+            "delay": 120,
+            "extra": False,
+            "cancelled": False,
+            "realtimePlatform": "5",
+        },
+        {
+            "line": {
+                "name": "U1",
+                "direction": "Norderstedt Mitte",
+                "type": {"simpleType": "TRAIN", "shortInfo": "U"},
+                "id": "HHA-U:U1_HHA-U",
+            },
+            "timeOffset": 4,
+            "serviceId": 200023671,
+            "platform": "2",
+            "realtimePlatform": "3",
+            "delay": 0,
+            "extra": False,
+            "cancelled": False,
+        },
+        {
+            "line": {
+                "name": "S1",
+                "direction": "Wedel",
+                "type": {"simpleType": "TRAIN", "shortInfo": "S"},
+                "id": "DBAG-S:S1_DBAG-S",
+            },
+            "timeOffset": 9,
+            "serviceId": 200023672,
+            "platform": "3",
+            "cancelled": True,
+            "attributes": [{"title": "Hinweis", "value": "Bauarbeiten"}],
+        },
+    ],
+    "serviceTypes": ["BUS", "TRAIN"],
+}
+
+CHECK_NAME_RESPONSE = {
+    "returnCode": "OK",
+    "results": [
+        {
+            "name": "Christuskirche",
+            "city": "Hamburg",
+            "combinedName": "Christuskirche",
+            "id": "Master:84902",
+            "type": "STATION",
+            "coordinate": {"x": 9.93454, "y": 53.552405},
+            "serviceTypes": ["bus", "u"],
+            "hasStationInformation": True,
+        },
+        # Non-station suggestions must be filtered out
+        {"name": "Christuskirche 1", "city": "Hamburg", "id": "Coord:9.9,53.5", "type": "ADDRESS"},
+    ],
+}
+
+
+class _FakeResponse:
+    def __init__(self, status, payload):
+        self.status = status
+        self._payload = payload
+
+    async def json(self, content_type=None):
+        return self._payload
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *exc):
+        return False
+
+
+class _FakeSession:
+    """Records the exact bytes and headers of each POST."""
+
+    def __init__(self, status=200, payload=None):
+        self.status = status
+        self.payload = payload if payload is not None else {"returnCode": "OK"}
+        self.calls = []
+
+    def post(self, url, data=None, headers=None, timeout=None):
+        self.calls.append(SimpleNamespace(url=url, body=data, headers=headers))
+        return _FakeResponse(self.status, self.payload)
+
+
+def _provider(session) -> HVVGTIProvider:
+    return HVVGTIProvider(session, api_key="testuser", api_key_secondary="s3cr3t")
+
+
+# ── authentication ────────────────────────────────────────────────────────────
+
+
+def test_sign_request_matches_hmac_sha1_base64():
+    body = b'{"version":63}'
+    expected = base64.b64encode(hmac.new(b"s3cr3t", body, hashlib.sha1).digest()).decode()
+
+    assert sign_request("s3cr3t", body) == expected
+
+
+async def test_signature_covers_the_exact_bytes_sent():
+    """The body must be signed and transmitted as the same bytes.
+
+    Re-serialising the payload (e.g. handing aiohttp `json=`) would change the
+    bytes and the server would reject the signature.
+    """
+    session = _FakeSession(payload=CHECK_NAME_RESPONSE)
+    await _provider(session).search_stops("Christuskirche")
+
+    call = session.calls[0]
+    assert isinstance(call.body, bytes)
+    assert call.headers["geofox-auth-signature"] == sign_request("s3cr3t", call.body)
+    assert call.headers["geofox-auth-type"] == "HmacSHA1"
+    assert call.headers["geofox-auth-user"] == "testuser"
+
+
+async def test_request_pins_the_api_version():
+    session = _FakeSession(payload=CHECK_NAME_RESPONSE)
+    await _provider(session).search_stops("Christuskirche")
+
+    body = json.loads(session.calls[0].body.decode("utf-8"))
+    assert body["version"] == 63
+    assert body["language"] == "de"
+
+
+async def test_missing_credentials_raise():
+    provider = HVVGTIProvider(_FakeSession(), api_key="testuser", api_key_secondary=None)
+
+    with pytest.raises(AuthenticationError):
+        await provider.fetch_departures("Master:84902", "", "", 10)
+
+
+@pytest.mark.parametrize("status", [401, 403])
+async def test_http_401_403_raise_authentication_error(status):
+    provider = _provider(_FakeSession(status=status))
+
+    with pytest.raises(AuthenticationError):
+        await provider.search_stops("Christuskirche")
+
+
+async def test_non_ok_return_code_is_not_fatal():
+    session = _FakeSession(payload={"returnCode": "ERROR_TEXT", "errorText": "Unbekannte Haltestelle"})
+
+    assert await _provider(session).search_stops("Nirgendwo") == []
+
+
+async def test_http_error_returns_no_departures():
+    provider = _provider(_FakeSession(status=500))
+
+    assert await provider.fetch_departures("Master:84902", "", "", 10) is None
+
+
+# ── stop search ───────────────────────────────────────────────────────────────
+
+
+async def test_search_stops_keeps_only_stations():
+    session = _FakeSession(payload=CHECK_NAME_RESPONSE)
+
+    stops = await _provider(session).search_stops("Christuskirche")
+
+    assert stops == [
+        {"id": "Master:84902", "name": "Christuskirche", "place": "Hamburg", "area_type": "stop"}
+    ]
+    assert session.calls[0].url == "https://gti.geofox.de/gti/public/checkName"
+
+
+# ── departures ────────────────────────────────────────────────────────────────
+
+
+async def _departures(limit=10):
+    session = _FakeSession(payload=DEPARTURE_LIST_RESPONSE)
+    provider = _provider(session)
+    data = await provider.fetch_departures("Master:84902", "", "", limit)
+    return provider, session, data
+
+
+async def test_departure_list_request_shape():
+    _, session, _ = await _departures()
+
+    body = json.loads(session.calls[0].body.decode("utf-8"))
+    assert session.calls[0].url == "https://gti.geofox.de/gti/public/departureList"
+    assert body["station"] == {"id": "Master:84902", "type": "STATION"}
+    assert body["useRealtime"] is True
+    assert body["maxTimeOffset"] == 200
+    # GTITime is dd.MM.yyyy / HH:mm, not ISO
+    assert len(body["time"]["date"].split(".")) == 3
+    assert ":" in body["time"]["time"]
+
+
+async def test_station_id_is_required():
+    provider = _provider(_FakeSession(payload=DEPARTURE_LIST_RESPONSE))
+
+    assert await provider.fetch_departures(None, "Hamburg", "Christuskirche", 10) is None
+
+
+async def test_departures_are_sorted_and_limited():
+    _, _, data = await _departures(limit=2)
+
+    assert [event["line"] for event in data["stopEvents"]] == ["U1", "S1"]
+
+
+async def test_time_offset_minutes_plus_delay_seconds():
+    """planned = board reference + timeOffset; estimated adds the delay.
+
+    Matches how Home Assistant core's own hvv_departures integration reads
+    these two fields.
+    """
+    provider, _, data = await _departures()
+    bus = next(event for event in data["stopEvents"] if event["line"] == "476")
+
+    departure = provider.parse_departure(bus, TZ, NOW)
+
+    assert departure.planned_time == "21:48"  # 21:28 + 20 min
+    assert departure.departure_time == "21:50"  # + 120 s
+    assert departure.delay == 2
+    assert departure.is_realtime is True
+    assert departure.minutes_until_departure == 22
+
+
+async def test_realtime_platform_wins_and_flags_a_change():
+    provider, _, data = await _departures()
+    subway = next(event for event in data["stopEvents"] if event["line"] == "U1")
+
+    departure = provider.parse_departure(subway, TZ, NOW)
+
+    assert departure.platform == "3"
+    assert departure.planned_platform == "2"
+    assert departure.platform_changed is True
+    assert departure.to_dict()["platform_changed"] is True
+
+
+async def test_unchanged_platform_is_not_a_change():
+    provider, _, data = await _departures()
+    bus = next(event for event in data["stopEvents"] if event["line"] == "476")
+
+    departure = provider.parse_departure(bus, TZ, NOW)
+
+    assert departure.platform == "5"
+    assert departure.platform_changed is False
+
+
+async def test_cancellation_and_attributes_become_notices():
+    provider, _, data = await _departures()
+    s_bahn = next(event for event in data["stopEvents"] if event["line"] == "S1")
+
+    departure = provider.parse_departure(s_bahn, TZ, NOW)
+
+    assert "Bauarbeiten" in departure.notices
+    assert "Fahrt fällt aus" in departure.notices
+    # No `delay` field at all → not real-time controlled
+    assert departure.is_realtime is False
+    assert departure.delay == 0
+
+
+@pytest.mark.parametrize(
+    ("line", "expected"),
+    [
+        ({"name": "U1", "type": {"simpleType": "TRAIN", "shortInfo": "U"}}, "subway"),
+        ({"name": "S1", "type": {"simpleType": "TRAIN", "shortInfo": "S"}}, "train"),
+        ({"name": "A1", "type": {"simpleType": "TRAIN", "shortInfo": "AKN"}}, "train"),
+        ({"name": "476", "type": {"simpleType": "BUS"}}, "bus"),
+        ({"name": "X35", "type": {"simpleType": "BUS", "shortInfo": "XpressBus"}}, "bus"),
+        ({"name": "62", "type": {"simpleType": "SHIP", "shortInfo": "Fähre"}}, "ferry"),
+        ({"name": "8000", "type": {"simpleType": "BUS", "shortInfo": "AST"}}, "taxi"),
+        # Coarse TRAIN with no shortInfo — the line name settles it
+        ({"name": "U3", "type": {"simpleType": "TRAIN"}}, "subway"),
+        ({"name": "S31", "type": {"simpleType": "TRAIN"}}, "train"),
+        ({"name": "???", "type": {}}, "unknown"),
+    ],
+)
+def test_transport_type_mapping(line, expected):
+    from openpublictransport.providers.hvv_gti import _transport_type
+
+    assert _transport_type(line) == expected
+
+
+async def test_departure_without_time_offset_is_skipped():
+    session = _FakeSession(
+        payload={
+            "returnCode": "OK",
+            "time": {"date": "01.08.2026", "time": "21:28"},
+            "departures": [{"line": {"name": "476"}}],
+        }
+    )
+
+    data = await _provider(session).fetch_departures("Master:84902", "", "", 10)
+
+    assert data == {"stopEvents": []}
+
+
+async def test_unparseable_reference_time_falls_back():
+    session = _FakeSession(
+        payload={
+            "returnCode": "OK",
+            "time": {"date": "nonsense", "time": "??"},
+            "departures": [{"line": {"name": "476", "type": {"simpleType": "BUS"}}, "timeOffset": 5}],
+        }
+    )
+
+    data = await _provider(session).fetch_departures("Master:84902", "", "", 10)
+
+    assert len(data["stopEvents"]) == 1
+
+
+# ── registry ──────────────────────────────────────────────────────────────────
+
+
+def test_provider_is_registered_and_needs_a_key():
+    provider = get_provider("hvv_gti", None, api_key="u", api_key_secondary="p")
+
+    assert isinstance(provider, HVVGTIProvider)
+    assert provider.requires_api_key is True
+    assert provider.get_timezone() == "Europe/Berlin"
+
+
+def test_efa_hvv_provider_is_untouched():
+    """The existing keyless `hvv` provider must keep working — the IDs are load-bearing."""
+    from openpublictransport.providers.hvv import HVVProvider
+
+    provider = get_provider("hvv", None)
+
+    assert isinstance(provider, HVVProvider)
+    assert provider.requires_api_key is False