LTADatamall-py 0.1.0__tar.gz

ltadatamall_py-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joel Khor / TheReaper62
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ltadatamall_py-0.1.0/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: LTADatamall-py
+Version: 0.1.0
+Summary: LTA Datamall API Wrapper
+Author-email: FishballNoodles <joelkhor.work@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/TheReaper62/ltadatamall-py
+Project-URL: Bug_Tracker, https://github.com/TheReaper62/ltadatamall-py/issues
+Keywords: lta,datamall,bus,timing,arrival,train,service,passenger volume,taxi
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Requires-Dist: aiohttp>=3.9.0
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.5; extra == "docs"
+Requires-Dist: mkdocs-material>=9.5; extra == "docs"
+Requires-Dist: mkdocstrings[python]>=0.24; extra == "docs"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: python-dotenv>=1.0; extra == "dev"
+Dynamic: license-file
+
+## LTA Datamall API Wrapper (Python)
+
+> This is an Unoffical Wrapper and this repo has no relation nor endorsement with/from LTA
+> ####v0.1.0
+> **Library Features:**
+
+- Sync/Async
+- Lightweight
+- Easy to Use
+- Open Source
+
+### Setup
+
+---
+
+##### Windows
+
+```shell
+>>> pip install LTADatamall_py
+```
+
+##### MacOS
+
+```shell
+>>> pip3 install LTADatamall_py
+```
+
+### Services/Information Provided
+
+---
+
+1. Bus Related
+
+   - Bus Arrival
+   - Bus Stop
+   - Bus Route
+2. Passenger Volume
+
+   - Train Station
+   - Bus Stop
+3. Train Service Alert
+
+   - Train Service Alert Messages

ltadatamall_py-0.1.0/README.md

@@ -0,0 +1,43 @@
+## LTA Datamall API Wrapper (Python)
+
+> This is an Unoffical Wrapper and this repo has no relation nor endorsement with/from LTA
+> ####v0.1.0
+> **Library Features:**
+
+- Sync/Async
+- Lightweight
+- Easy to Use
+- Open Source
+
+### Setup
+
+---
+
+##### Windows
+
+```shell
+>>> pip install LTADatamall_py
+```
+
+##### MacOS
+
+```shell
+>>> pip3 install LTADatamall_py
+```
+
+### Services/Information Provided
+
+---
+
+1. Bus Related
+
+   - Bus Arrival
+   - Bus Stop
+   - Bus Route
+2. Passenger Volume
+
+   - Train Station
+   - Bus Stop
+3. Train Service Alert
+
+   - Train Service Alert Messages

ltadatamall_py-0.1.0/pyproject.toml

@@ -0,0 +1,83 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "LTADatamall-py"
+version = "0.1.0"
+description = "LTA Datamall API Wrapper"
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "MIT"}
+authors = [
+    {name = "FishballNoodles", email = "joelkhor.work@gmail.com"}
+]
+keywords = [
+    "lta", "datamall", "bus", "timing", "arrival", "train", 
+    "service", "passenger volume", "taxi"
+]
+
+dependencies = [
+    "requests>=2.31.0",
+    "aiohttp>=3.9.0",
+]
+
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Build Tools",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+
+[project.urls]
+Homepage = "https://github.com/TheReaper62/ltadatamall-py"
+Bug_Tracker = "https://github.com/TheReaper62/ltadatamall-py/issues"
+
+[project.optional-dependencies]
+docs = [
+    "mkdocs>=1.5",
+    "mkdocs-material>=9.5",
+    "mkdocstrings[python]>=0.24",
+]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=4.0",
+    "pytest-asyncio>=0.23",
+    "python-dotenv>=1.0",
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+namespaces = false
+
+[tool.pytest.ini_options]
+minversion = "8.0"
+addopts = "-ra -q --cov=ltadatamall --cov-report=term-missing"
+testpaths = ["tests"]
+asyncio_mode = "auto"
+markers = [
+    "core: marks tests as core functionality tests",
+    "async: marks tests that test asynchronous functionality",
+]
+
+[tool.coverage.run]
+source = ["ltadatamall"]
+branch = true
+
+[tool.coverage.report]
+exclude_also = [
+    "def __repr__",
+    "if __name__ == .__main__.:",
+    "if TYPE_CHECKING:",
+    "raise AssertionError",
+    "raise NotImplementedError",
+]
+fail_under = 90

ltadatamall_py-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ltadatamall_py-0.1.0/src/LTADatamall_py.egg-info/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: LTADatamall-py
+Version: 0.1.0
+Summary: LTA Datamall API Wrapper
+Author-email: FishballNoodles <joelkhor.work@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/TheReaper62/ltadatamall-py
+Project-URL: Bug_Tracker, https://github.com/TheReaper62/ltadatamall-py/issues
+Keywords: lta,datamall,bus,timing,arrival,train,service,passenger volume,taxi
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Requires-Dist: aiohttp>=3.9.0
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.5; extra == "docs"
+Requires-Dist: mkdocs-material>=9.5; extra == "docs"
+Requires-Dist: mkdocstrings[python]>=0.24; extra == "docs"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: python-dotenv>=1.0; extra == "dev"
+Dynamic: license-file
+
+## LTA Datamall API Wrapper (Python)
+
+> This is an Unoffical Wrapper and this repo has no relation nor endorsement with/from LTA
+> ####v0.1.0
+> **Library Features:**
+
+- Sync/Async
+- Lightweight
+- Easy to Use
+- Open Source
+
+### Setup
+
+---
+
+##### Windows
+
+```shell
+>>> pip install LTADatamall_py
+```
+
+##### MacOS
+
+```shell
+>>> pip3 install LTADatamall_py
+```
+
+### Services/Information Provided
+
+---
+
+1. Bus Related
+
+   - Bus Arrival
+   - Bus Stop
+   - Bus Route
+2. Passenger Volume
+
+   - Train Station
+   - Bus Stop
+3. Train Service Alert
+
+   - Train Service Alert Messages

ltadatamall_py-0.1.0/src/LTADatamall_py.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+LICENSE
+README.md
+pyproject.toml
+src/LTADatamall_py.egg-info/PKG-INFO
+src/LTADatamall_py.egg-info/SOURCES.txt
+src/LTADatamall_py.egg-info/dependency_links.txt
+src/LTADatamall_py.egg-info/requires.txt
+src/LTADatamall_py.egg-info/top_level.txt
+src/ltadatamall/__init__.py
+src/ltadatamall/base.py
+src/ltadatamall/bus_arrival.py
+src/ltadatamall/bus_manager.py
+src/ltadatamall/bus_route.py
+src/ltadatamall/bus_service.py
+src/ltadatamall/bus_stop.py
+src/ltadatamall/passenger_volume.py
+src/ltadatamall/taxi.py
+src/ltadatamall/train_service_alert.py

ltadatamall_py-0.1.0/src/LTADatamall_py.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

ltadatamall_py-0.1.0/src/LTADatamall_py.egg-info/requires.txt

@@ -0,0 +1,13 @@
+requests>=2.31.0
+aiohttp>=3.9.0
+
+[dev]
+pytest>=8.0
+pytest-cov>=4.0
+pytest-asyncio>=0.23
+python-dotenv>=1.0
+
+[docs]
+mkdocs>=1.5
+mkdocs-material>=9.5
+mkdocstrings[python]>=0.24

ltadatamall_py-0.1.0/src/LTADatamall_py.egg-info/top_level.txt

@@ -0,0 +1 @@
+ltadatamall

ltadatamall_py-0.1.0/src/ltadatamall/__init__.py

@@ -0,0 +1,8 @@
+'''
+Authors: TheReaper62
+'''
+
+from .bus_manager import *
+from .passenger_volume import *
+from .taxi import *
+from .train_service_alert import *

ltadatamall_py-0.1.0/src/ltadatamall/base.py

@@ -0,0 +1,64 @@
+'''
+Authors: TheReaper62
+'''
+
+from typing import Any, Optional
+
+import httpx
+from requests import Session, exceptions
+
+
+class BaseModel:
+    """
+    Base class for all model classes.
+    Contains the send and async_send methods for sending requests to the API.
+    """
+
+    BASE_URL = "https://datamall2.mytransport.sg/ltaodataservice"
+
+    def __init__(self, api_key: str):
+        self.headers = {"Accept": "application/json", "AccountKey": api_key}
+
+    def send(
+        self,
+        path,
+        *,
+        params: Optional[dict[str, Any]] = None,
+        json: Optional[dict[str, Any]] = None,
+    ) -> dict[str, Any]:
+        """Sends a request to the API and returns the response as a JSON object."""
+        with Session() as session:
+            response = session.get(
+                BaseModel.BASE_URL + "/" + path,
+                params=params,
+                headers=self.headers,
+                json=json,
+            )
+            try:
+                response.raise_for_status()
+                return response.json()
+            except exceptions.HTTPError as error:
+                raise exceptions.HTTPError(f"An Error Occured: {error}") from None
+
+    async def async_send(
+        self, path: str, *, params: dict[str, Any], json: dict[str, Any]
+    ) -> dict[str, Any]:
+        """Sends an asynchronous request to the API and returns the response as a JSON object."""
+        url = f"{BaseModel.BASE_URL}/{path}"
+
+        async with httpx.AsyncClient() as client:
+            try:
+                response = await client.get(
+                    url, params=params, headers=self.headers, json=json
+                )
+                response.raise_for_status()
+                return response.json()
+
+            except httpx.HTTPStatusError as error:
+                # Captures 4xx and 5xx responses specifically
+                raise exceptions.HTTPError(f"An Error Occurred: {error}") from None
+            except httpx.RequestError as error:
+                # Captures underlying network issues (e.g., connection timeouts)
+                raise exceptions.HTTPError(
+                    f"A Network Error Occurred: {error}"
+                ) from None

ltadatamall_py-0.1.0/src/ltadatamall/bus_arrival.py

@@ -0,0 +1,121 @@
+from typing import Optional, Unpack, TypedDict
+from datetime import datetime
+import zoneinfo
+
+__all__ = [
+    'NextBus',
+    'BusArrivalService',
+]
+
+
+class NextBusPayload(TypedDict, total=False):
+    OriginCode: str
+    DestinationCode: str
+    EstimatedArrival: str
+    Latitude: str
+    Longitude: str
+    VisitNumber: str
+    Load: str
+    Feature: str
+    Type: str
+
+
+class NextBus:
+    """
+    Represents an arriving bus service with parsed telemetry and capacity data.
+
+    This class ingests raw API response payloads via keyword arguments, normalizes 
+    codes into human-readable strings, and parses arrival timestamps into timezone-aware 
+    datetime objects.
+    """
+
+    def __init__(self, **kwargs: Unpack[NextBusPayload]) -> None:
+        load_map = {
+            "SEA": "Seats Available",
+            "SDA": "Standing Available",
+            "LSD": "Limited Standing",
+        }
+        type_map = {"SD": "Single Decker", "DD": "Double Decker", "BD": "Bendy"}
+
+        self.origin_code = kwargs.get("OriginCode", "Not Available")
+        self.destination_code = kwargs.get("DestinationCode", "Not Available")
+
+        self.estimated_arrival = (
+            datetime.strptime(kwargs["EstimatedArrival"], r"%Y-%m-%dT%H:%M:%S%z")
+            if kwargs.get("EstimatedArrival", "") != ""
+            else "No Estimated Time"
+        )
+        self.latitude = kwargs.get("Latitude", 0.0)
+        self.longitude = kwargs.get("Longitude", 0.0)
+
+        self.visit_number = (
+            int(kwargs["VisitNumber"])
+            if kwargs.get("VisitNumber", "") != ""
+            else "Not Available"
+        )
+        self.load = load_map.get(kwargs.get("Load", None), "Not Available")
+        self.feature = (
+            "Not Wheel-chair Accessible"
+            if kwargs.get("Feature", "") == ""
+            else "Wheel-chair Accessible"
+        )
+        self.type = type_map.get(kwargs.get("Type"), "Not Available")
+
+
+class BusArrivalServicePayload(TypedDict, total=False):
+    ServiceNo: str
+    Operator: str
+    NextBus: NextBusPayload
+    NextBus2: NextBusPayload
+    NextBus3: NextBusPayload
+
+
+class BusArrivalService:
+    """Model representing arrival information for a specific bus service at a bus stop.
+
+    This class parses metadata for a distinct transit route code and instantiates
+    the upcoming three scheduled arrival vehicle telemetry profiles.
+    """
+
+    def __init__(self, **kwargs: Unpack[BusArrivalServicePayload]) -> None:
+        operator_map: dict[str, str] = {
+            "SBST": "SBS Transit",
+            "SMRT": "SMRT Corporation",
+            "TTS": "Tower Transit Singapore",
+            "GAS": "Go Ahead Singapore",
+        }
+
+        # Handle explicit type coercions safely
+        raw_service_no = kwargs.get("ServiceNo")
+        self.service_no: Optional[int] = (
+            int(raw_service_no) if raw_service_no is not None else None
+        )
+
+        self.operator: str = operator_map.get(
+            kwargs.get("Operator", ""), "Not Available"
+        )
+
+        # 2. Extract nested structures and instantiate NextBus objects cleanly
+        self.next_1: NextBus = NextBus(**kwargs.get("NextBus", {}))
+        self.next_2: NextBus = NextBus(**kwargs.get("NextBus2", {}))
+        self.next_3: NextBus = NextBus(**kwargs.get("NextBus3", {}))
+
+        self.secs_to_arrival: Optional[int] = None
+        self._calculate_seconds_to_arrival()
+
+    def _calculate_seconds_to_arrival(self) -> None:
+        """Calculates time delta between now and next_1 arrival in seconds."""
+        if (
+            isinstance(self.next_1.estimated_arrival, str)
+            or self.next_1.estimated_arrival == "No Estimated Time"
+        ):
+            self.secs_to_arrival = None
+            return
+
+        sg_tz = zoneinfo.ZoneInfo("Asia/Singapore")
+        now_sg = datetime.now(sg_tz)
+
+        time_delta = self.next_1.estimated_arrival - now_sg
+        total_seconds = int(time_delta.total_seconds())
+
+        self.secs_to_arrival = total_seconds

ltadatamall_py-0.1.0/src/ltadatamall/bus_manager.py

@@ -0,0 +1,366 @@
+from typing import Any
+
+from .base import BaseModel
+
+from .bus_stop import BusStop
+from .bus_service import BusService
+from .bus_route import BusRoute
+from .bus_arrival import BusArrivalService
+
+__all__ = (
+    'BusManager',
+)
+
+
+class BusManager(BaseModel):
+    """Orchestrates API for tracking bus routes and operational status profiles."""
+
+    def get_bus_arrival(
+        self,
+        bus_stop_code: str | int | BusStop,
+        *,
+        service_no: str | int | None = None,
+    ) -> list[BusArrivalService]:
+        """Fetches real-time bus arrival timelines for a specific bus stop code.
+
+        Args:
+            bus_stop_code: The 5-digit unique transit stop code or a BusStop instance.
+            service_no: Optional specific transit service route number to filter results.
+
+        Returns:
+            A list containing active BusArrivalService status track records.
+        """
+        params = self._prepare_arrival_params(bus_stop_code, service_no)
+        response = self.send("v3/BusArrival", params=params)
+
+        services = response.get("Services")
+        if isinstance(services, list):
+            return [BusArrivalService(**item) for item in services]
+
+        raise ValueError(
+            f"LTA DataMall API did not yield any service items for parameters: {params}"
+        )
+
+    async def async_get_bus_arrival(
+        self,
+        bus_stop_code: str | int | BusStop,
+        *,
+        service_no: str | int | None = None,
+    ) -> list[BusArrivalService]:
+        """Asynchronously fetches real-time bus arrival timelines for a specific bus stop code."""
+        params = self._prepare_arrival_params(bus_stop_code, service_no)
+
+        response = await self.async_send("v3/BusArrival", params=params, json=None)
+
+        services = response.get("Services")
+        if isinstance(services, list):
+            return [BusArrivalService(**item) for item in services]
+
+        raise ValueError(
+            "LTA DataMall API did not yield any service items for the specified parameters."
+        )
+
+    def _prepare_arrival_params(
+        self, bus_stop_code: str | int | BusStop, service_no: str | int | None
+    ) -> dict[str, Any]:
+        """Internal helper logic block designed to standardise all codes to strings."""
+        code = (
+            bus_stop_code.bus_stop_code
+            if isinstance(bus_stop_code, BusStop)
+            else str(bus_stop_code)
+        )
+
+        params: dict[str, Any] = {"BusStopCode": code}
+        if service_no is not None:
+            params["ServiceNo"] = str(service_no)
+
+        return params
+
+    def get_services(
+        self,
+        services: list[str | int] | None = None
+    ) -> list[BusService]:
+        """Fetches comprehensive metadata for active bus routes.
+
+        Args:
+            services: Optional explicit list of route numbers to filter. 
+                If None, all available services are returned.
+        """
+        response = self.send("BusServices")
+        value_list = response.get("value")
+
+        if not isinstance(value_list, list):
+            raise ValueError(
+                "LTA DataMall API did not yield a valid data list layout for BusServices."
+            )
+
+        if services is None:
+            return [BusService(**item) for item in value_list]
+
+        # Optimization: Use a hashed set lookup instead of rebuilding a map list inside a loop
+        target_services = {str(s) for s in services}
+        return [
+            BusService(**item)
+            for item in value_list
+            if str(item.get("ServiceNo")) in target_services
+        ]
+
+    async def async_get_services(
+        self,
+        services: list[str | int] | None = None
+    ) -> list[BusService]:
+        """Asynchronously fetches comprehensive metadata for active bus routes."""
+        response = await self.async_send("BusServices", params=None, json=None)
+        value_list = response.get("value")
+
+        if not isinstance(value_list, list):
+            raise ValueError(
+                "LTA DataMall API did not yield a valid data list layout for BusServices."
+            )
+
+        if services is None:
+            return [BusService(**item) for item in value_list]
+
+        target_services = {str(s) for s in services}
+        return [
+            BusService(**item)
+            for item in value_list
+            if str(item.get("ServiceNo")) in target_services
+        ]
+
+    def get_all_services(self) -> list[BusService]:
+        """Fetches all active bus service records by automatically paginating
+        through the 500-record payload threshold constraints.
+        """
+        services: list[BusService] = []
+        skip_offset = 0
+
+        while True:
+            response = self.send("BusServices", params={"$skip": skip_offset})
+            records = response.get("value")
+
+            if not isinstance(records, list) or not records:
+                if skip_offset == 0:
+                    raise ValueError(
+                        "LTA DataMall API returned an empty or invalid BusServices payload."
+                    )
+                break
+            services.extend([BusService(**item) for item in records])
+
+            if len(records) < 500:
+                break
+            skip_offset += 500
+        return services
+
+    async def async_get_all_services(self) -> list[BusService]:
+        """Asynchronously fetches all active bus service records by handling pagination."""
+        services: list[BusService] = []
+        skip_offset = 0
+
+        while True:
+            response = await self.async_send(
+                "BusServices", params={"$skip": skip_offset}, json=None
+            )
+            records = response.get("value")
+
+            if not isinstance(records, list) or not records:
+                if skip_offset == 0:
+                    raise ValueError(
+                        "LTA DataMall API returned an empty or invalid BusServices payload."
+                    )
+                break
+            services.extend([BusService(**item) for item in records])
+
+            if len(records) < 500:
+                break
+            skip_offset += 500
+        return services
+
+    def get_routes(self, **filters: Any) -> list[BusRoute]:
+        """Fetches a single page of bus route data and applies filters.
+
+        Args:
+            **filters: Optional keyword arguments matching model attributes 
+                (e.g., service_no="190", bus_stop_code="65009").
+        """
+        # FIX: Standardized endpoint path from singular 'BusRoute' to plural 'BusRoutes'
+        response = self.send("BusRoutes")
+        value_list = response.get("value")
+
+        if not isinstance(value_list, list):
+            raise ValueError("LTA DataMall API did not yield a valid data list layout for BusRoutes.")
+
+        if not filters:
+            return [BusRoute(**item) for item in value_list]
+
+        # Map Python snake_case filters to LTA PascalCase keys
+        pascal_filters = self._normalize_filters(filters)
+
+        return [
+            BusRoute(**item)
+            for item in value_list
+            if all(item.get(k) == v for k, v in pascal_filters.items())
+        ]
+
+    async def async_get_routes(self, **filters: Any) -> list[BusRoute]:
+        """Asynchronously fetches a single page of bus route data and applies filters."""
+        # FIX 1: Added await keyword
+        # FIX 2: Corrected endpoint from singular to plural 'BusRoutes'
+        # FIX 3: Supplied json=None keyword matching BaseModel signature
+        response = await self.async_send("BusRoutes", params=None, json=None)
+        value_list = response.get("value")
+
+        if not isinstance(value_list, list):
+            raise ValueError("LTA DataMall API did not yield a valid data list layout for BusRoutes.")
+
+        if not filters:
+            return [BusRoute(**item) for item in value_list]
+
+        pascal_filters = self._normalize_filters(filters)
+
+        return [
+            BusRoute(**item)
+            for item in value_list
+            if all(item.get(k) == v for k, v in pascal_filters.items())
+        ]
+
+    def get_all_routes(self) -> list[BusRoute]:
+        """Fetches all bus route records by automatically handling the 500-record pagination limit."""
+        routes: list[BusRoute] = []
+        skip_offset = 0
+
+        while True:
+            response = self.send("BusRoutes", params={"$skip": skip_offset})
+            records = response.get("value")
+            if not isinstance(records, list) or not records:
+                if skip_offset == 0:
+                    raise ValueError("LTA DataMall API returned an empty or invalid BusRoutes payload.")
+                break
+            routes.extend([BusRoute(**item) for item in records])
+
+            if len(records) < 500:
+                break
+            skip_offset += 500
+        return routes
+
+    async def async_get_all_routes(self) -> list[BusRoute]:
+        """Asynchronously fetches all bus route records by handling pagination constraints cleanly."""
+        routes: list[BusRoute] = []
+        skip_offset = 0
+
+        while True:
+            response = await self.async_send("BusRoutes", params={"$skip": skip_offset}, json=None)
+            records = response.get("value")
+            if not isinstance(records, list) or not records:
+                if skip_offset == 0:
+                    raise ValueError("LTA DataMall API returned an empty or invalid BusRoutes payload.")
+                break
+            routes.extend([BusRoute(**item) for item in records])
+
+            if len(records) < 500:
+                break
+            skip_offset += 500
+        return routes
+
+    def _normalize_filters(self, filters: dict[str, Any]) -> dict[str, Any]:
+        """Helper to map common snake_case filter keys to LTA data field shapes."""
+        mapping = {
+            "service_no": "ServiceNo",
+            "operator": "Operator",
+            "direction": "Direction",
+            "stop_sequence": "StopSequence",
+            "bus_stop_code": "BusStopCode",
+        }
+        return {mapping.get(k, k): v for k, v in filters.items()}
+
+    def get_stops(self, bus_stop_codes: str | int | list[str | int]) -> list[BusStop] | BusStop | None:
+        """Retrieves targeted bus stop configurations from the complete database.
+
+        Args:
+            bus_stop_codes: A single stop code (str/int) or a sequence array of stop codes.
+
+        Returns:
+            A single BusStop object if a scalar input was provided, a list of BusStop 
+            objects if a sequence was provided, or None if no matches were located.
+        """
+        raw_stops = self._fetch_raw_all_stops()
+
+        if isinstance(bus_stop_codes, (str, int)):
+            target_code = str(bus_stop_codes)
+            for item in raw_stops:
+                if str(item.get("BusStopCode")) == target_code:
+                    return BusStop(**item)
+            return None
+
+        search_set = {str(code) for code in bus_stop_codes}
+        return [
+            BusStop(**item)
+            for item in raw_stops
+            if str(item.get("BusStopCode")) in search_set
+        ]
+
+    async def async_get_stops(self, bus_stop_codes: str | int | list[str | int]) -> list[BusStop] | BusStop | None:
+        """Asynchronously retrieves targeted bus stop configurations from the complete database."""
+        raw_stops = await self._async_fetch_raw_all_stops()
+
+        if isinstance(bus_stop_codes, (str, int)):
+            target_code = str(bus_stop_codes)
+            for item in raw_stops:
+                if str(item.get("BusStopCode")) == target_code:
+                    return BusStop(**item)
+            return None
+
+        search_set = {str(code) for code in bus_stop_codes}
+        return [
+            BusStop(**item)
+            for item in raw_stops
+            if str(item.get("BusStopCode")) in search_set
+        ]
+
+    def get_all_stops(self) -> list[BusStop]:
+        """Fetches all bus stop configurations registered on the LTA network."""
+        return [BusStop(**item) for item in self._fetch_raw_all_stops()]
+
+    async def async_get_all_stops(self) -> list[BusStop]:
+        """Asynchronously fetches all bus stop configurations registered on the LTA network."""
+        return [BusStop(**item) for item in await self._async_fetch_raw_all_stops()]
+
+    def _fetch_raw_all_stops(self) -> list[dict[str, Any]]:
+        """Internal helper to download raw payload dictionaries before class instantiation."""
+        stops: list[dict[str, Any]] = []
+        skip_offset = 0
+
+        while True:
+            response = self.send("BusStops", params={"$skip": skip_offset})
+            records = response.get("value")
+
+            if not isinstance(records, list) or not records:
+                if skip_offset == 0:
+                    raise ValueError("LTA DataMall API returned an empty or invalid BusStops payload.")
+                break
+            stops.extend(records)
+
+            if len(records) < 500:
+                break
+            skip_offset += 500
+        return stops
+
+    async def _async_fetch_raw_all_stops(self) -> list[dict[str, Any]]:
+        """Internal helper to asynchronously download raw payload dictionaries."""
+        stops: list[dict[str, Any]] = []
+        skip_offset = 0
+
+        while True:
+            response = await self.async_send("BusStops", params={"$skip": skip_offset}, json=None)
+            records = response.get("value")
+
+            if not isinstance(records, list) or not records:
+                if skip_offset == 0:
+                    raise ValueError("LTA DataMall API returned an empty or invalid BusStops payload.")
+                break
+            stops.extend(records)
+
+            if len(records) < 500:
+                break
+            skip_offset += 500
+        return stops

ltadatamall_py-0.1.0/src/ltadatamall/bus_route.py

@@ -0,0 +1,71 @@
+from typing import TypedDict, Unpack
+
+from .base import BaseModel
+
+__all__ = [
+    "BusRoute",
+]
+
+
+class BusRoutePayload(TypedDict, total=False):
+    ServiceNo: str
+    Operator: str
+    Direction: int | str
+    StopSequence: int | str
+    BusStopCode: str | int
+    Distance: float | str
+    WD_FirstBus: str
+    WD_LastBus: str
+    SAT_FirstBus: str
+    SAT_LastBus: str
+    SUN_FirstBus: str
+    SUN_LastBus: str
+
+
+class BusRoute:
+    """Model representing a sequential bus route stop entry.
+
+    This class handles specific schedule timings, distance metrics, and sequencing
+    indices for unique service routes across Singapore's transit network.
+    """
+
+    def __init__(self, **kwargs: Unpack[BusRoutePayload]) -> None:
+        operator_map: dict[str, str] = {
+            "SBST": "SBS Transit",
+            "SMRT": "SMRT Corporation",
+            "TTS": "Tower Transit Singapore",
+            "GAS": "Go Ahead Singapore",
+        }
+
+        self.service_no: str | None = kwargs.get("ServiceNo", None)
+
+        self.operator: str = operator_map.get(
+            kwargs.get("Operator", ""), "Not Available"
+        )
+
+        self.direction: int | None = (
+            int(kwargs["Direction"]) if kwargs.get("Direction") is not None else None
+        )
+        self.stop_sequence: int | None = (
+            int(kwargs["StopSequence"])
+            if kwargs.get("StopSequence") is not None
+            else None
+        )
+
+        self.bus_stop_code: str | None = (
+            str(kwargs["BusStopCode"])
+            if kwargs.get("BusStopCode") is not None
+            else None
+        )
+
+        self.distance: float | None = (
+            float(kwargs["Distance"]) if kwargs.get("Distance") is not None else None
+        )
+
+        # Timeline schedule fields
+        self.wd_firstbus: str | None = kwargs.get("WD_FirstBus", None)
+        self.wd_lastbus: str | None = kwargs.get("WD_LastBus", None)
+        self.sat_firstbus: str | None = kwargs.get("SAT_FirstBus", None)
+        self.sat_lastbus: str | None = kwargs.get("SAT_LastBus", None)
+        self.sun_firstbus: str | None = kwargs.get("SUN_FirstBus", None)
+        self.sun_lastbus: str | None = kwargs.get("SUN_LastBus", None)

ltadatamall_py-0.1.0/src/ltadatamall/bus_service.py

@@ -0,0 +1,53 @@
+from typing import TypedDict, Unpack
+
+from .base import BaseModel
+
+__all__ = [
+    "BusService",
+]
+
+
+class BusServicePayload(TypedDict, total=False):
+    ServiceNo: str
+    Operator: str
+    Direction: int | str
+    Category: str
+    OriginCode: str
+    DestinationCode: str
+    AM_Peak_Freq: str
+    AM_Offpeak_Freq: str
+    PM_Peak_Freq: str
+    PM_Offpeak_Freq: str
+    LoopDesc: str
+
+
+class BusService:
+    """Model representing metadata for a specific bus route service configuration.
+
+    This class extracts the operating schedule frequency, service loop descriptors,
+    and handling agency constraints from raw LTA data data streams.
+    """
+
+    def __init__(self, **kwargs: Unpack[BusServicePayload]) -> None:
+        operator_map: dict[str, str] = {
+            "SBST": "SBS Transit",
+            "SMRT": "SMRT Corporation",
+            "TTS": "Tower Transit Singapore",
+            "GAS": "Go Ahead Singapore",
+        }
+
+        self.service_no: str | None = kwargs.get("ServiceNo", None)
+        self.operator: str = operator_map.get(
+            kwargs.get("Operator", ""), "Not Available"
+        )
+        self.direction: int | None = (
+            int(kwargs["Direction"]) if kwargs.get("Direction") is not None else None
+        )
+        self.category: str | None = kwargs.get("Category", None)
+        self.origin_code: str | None = kwargs.get("OriginCode", None)
+        self.destination_code: str | None = kwargs.get("DestinationCode", None)
+        self.am_peak_freq: str | None = kwargs.get("AM_Peak_Freq", None)
+        self.am_offpeak_freq: str | None = kwargs.get("AM_Offpeak_Freq", None)
+        self.pm_peak_freq: str | None = kwargs.get("PM_Peak_Freq", None)
+        self.pm_offpeak_freq: str | None = kwargs.get("PM_Offpeak_Freq", None)
+        self.loop_desc: str | None = kwargs.get("LoopDesc", None)

ltadatamall_py-0.1.0/src/ltadatamall/bus_stop.py

@@ -0,0 +1,31 @@
+from typing import TypedDict, Unpack
+
+from .base import BaseModel
+
+__all__ = [
+    "BusStop",
+]
+
+
+class BusStopPayload(TypedDict, total=False):
+    BusStopCode: str | int
+    RoadName: str
+    Description: str
+    Latitude: str | float
+    Longitude: str | float
+
+
+class BusStop:
+    """Represents a physical bus stop containing metadata and geographic location coordinates.
+
+    This class ingests raw API response payloads via keyword arguments, normalizes
+    codes into human-readable strings, and forces coordinate parameters into float precision.
+    """
+
+    def __init__(self, **kwargs: Unpack[BusStopPayload]) -> None:
+        self.bus_stop_code: str = str(kwargs.get("BusStopCode", "Not Available"))
+        self.road_name: str = kwargs.get("RoadName", "Not Available")
+        self.description: str = kwargs.get("Description", "Not Available")
+
+        self.latitude: float = float(kwargs.get("Latitude", 0.0))
+        self.longitude: float = float(kwargs.get("Longitude", 0.0))

ltadatamall_py-0.1.0/src/ltadatamall/passenger_volume.py

@@ -0,0 +1,83 @@
+from .base import BaseModel
+
+__all__ = [
+    "PassengerVolume",
+]
+
+
+class PassengerVolume(BaseModel):
+    """Orchestrates LTA DataMall API bindings for monthly passenger volume downloads.
+
+    Provides dynamic downloadable asset links tracking transit volume matrices
+    across bus stops, train lines, and origin-destination nodes.
+    """
+
+    # 1. Passenger Volume By Bus Stop
+    def pv_bus_stop(self, date: str | None = None) -> str:
+        """Fetches the download URL link for passenger volumes by bus stops.
+
+        Args:
+            date: Targeted month in YYYYMM format (e.g., "202603"). Defaults
+                to the latest available month data from LTA if omitted.
+        """
+        params = {"Date": date} if date else None
+        response = self.send("PV/Bus", params=params)
+        return self._extract_download_link(response, "PV/Bus")
+
+    async def async_pv_bus_stop(self, date: str | None = None) -> str:
+        """Asynchronously fetches the download URL link for passenger volumes by bus stops."""
+        params = {"Date": date} if date else None
+        response = await self.async_send("PV/Bus", params=params, json=None)
+        return self._extract_download_link(response, "PV/Bus")
+
+    # 2. Passenger Volume By Origin-Destination Bus Stops
+    def pv_od_bus_stop(self, date: str | None = None) -> str:
+        """Fetches the download URL link for origin-destination passenger volumes by bus stops."""
+        params = {"Date": date} if date else None
+        response = self.send("PV/ODBus", params=params)
+        return self._extract_download_link(response, "PV/ODBus")
+
+    async def async_pv_od_bus_stop(self, date: str | None = None) -> str:
+        """Asynchronously fetches the download URL link for origin-destination passenger volumes by bus stops."""
+        params = {"Date": date} if date else None
+        response = await self.async_send("PV/ODBus", params=params, json=None)
+        return self._extract_download_link(response, "PV/ODBus")
+
+    # 3. Passenger Volume By Origin-Destination Train Stations
+    def pv_od_train_destination(self, date: str | None = None) -> str:
+        """Fetches the download URL link for origin-destination passenger volumes by train stations."""
+        params = {"Date": date} if date else None
+        response = self.send("PV/ODTrain", params=params)
+        return self._extract_download_link(response, "PV/ODTrain")
+
+    async def async_pv_od_train_destination(self, date: str | None = None) -> str:
+        """Asynchronously fetches the download URL link for origin-destination passenger volumes by train stations."""
+        params = {"Date": date} if date else None
+        response = await self.async_send("PV/ODTrain", params=params, json=None)
+        return self._extract_download_link(response, "PV/ODTrain")
+
+    # 4. Passenger Volume By Train Stations
+    def pv_train_station(self, date: str | None = None) -> str:
+        """Fetches the download URL link for passenger volumes by individual train stations."""
+        params = {"Date": date} if date else None
+        response = self.send("PV/Train", params=params)
+        return self._extract_download_link(response, "PV/Train")
+
+    async def async_pv_train_station(self, date: str | None = None) -> str:
+        """Asynchronously fetches the download URL link for passenger volumes by individual train stations."""
+        params = {"Date": date} if date else None
+        response = await self.async_send("PV/Train", params=params, json=None)
+        return self._extract_download_link(response, "PV/Train")
+
+    def _extract_download_link(self, response: dict[str, any], endpoint: str) -> str:
+        """Safely extracts the nested download URL link from LTA's response payload array wrapper."""
+        value_list = response.get("value")
+
+        if isinstance(value_list, list) and len(value_list) > 0:
+            link = value_list[0].get("Link")
+            if link:
+                return str(link)
+
+        raise ValueError(
+            f"LTA DataMall API did not yield a valid download link structural layout for endpoint: '{endpoint}'"
+        )

ltadatamall_py-0.1.0/src/ltadatamall/taxi.py

@@ -0,0 +1,62 @@
+from typing import Union
+
+from .base import BaseModel
+
+__all = (
+    'TaxiManager',
+    'AvailableTaxi',
+    'TaxiStand',
+)
+
+class AvailableTaxi:
+    def __init__(self,**kwargs):
+        self.latitude = float(kwargs.get('Latitude',0))
+        self.longitude = float(kwargs.get('Longitude',0))
+
+class TaxiStand:
+    def __init__(self,**kwargs):
+        ownership_map = {
+            'LTA' : "Land Transport Authority",
+            'CCS' : "Clear Channel Singapore",
+            'Private' : "Private",
+        }
+        self.taxi_code = kwargs.get('TaxiCode', "Not Available")
+        self.latitude = float(kwargs.get('Latitude',0))
+        self.longitude = float(kwargs.get('Longitude',0))
+        self.bfa = kwargs.get('Bfa',"Not Available")
+        self.ownership = ownership_map.get(kwargs.get('Ownership',None),"Not Available")
+        self.type = kwargs.get('Type',"Not Available")
+        self.name = kwargs.get('Name',"Not Available")
+
+class TaxiManager(BaseModel):
+    def __init__(self, api_key: str):
+        super().__init__(api_key)
+
+    # Available Taxis
+    def get_availability(self):
+        response = self.send('Taxi-Availability')
+        if response.get('value',False):
+            return [AvailableTaxi(**i) for i in response['value']]
+        raise Exception("API Returned None")
+
+    async def async_get_availability(self):
+        response = await self.async_send('Taxi-Availability')
+        if response.get('value',False):
+            return [AvailableTaxi(**i) for i in response['value']]
+        raise Exception("API Returned None")
+
+    # Taxi Stands
+    def get_taxi_stands(self,taxi_codes:Union[str,list[str]]=[]):
+        response = self.send('TaxiStands')
+        taxi_codes = [taxi_codes] if not isinstance(taxi_codes,(tuple,list)) else taxi_codes
+        if response.get('value',False):
+            return [TaxiStand(**i) for i in response['value'] if i['TaxiCode'] in taxi_codes and taxi_codes!=[]]
+        raise Exception("API Returned None")
+
+    async def async_get_taxi_stands(self, taxi_codes: Union[str, list[str]] = []):
+        response = await self.async_send('TaxiStands')
+        taxi_codes = [taxi_codes] if not isinstance(
+            taxi_codes, (tuple, list)) else taxi_codes
+        if response.get('value', False):
+            return [TaxiStand(**i) for i in response['value'] if i['TaxiCode'] in taxi_codes and taxi_codes != []]
+        raise Exception("API Returned None")

ltadatamall_py-0.1.0/src/ltadatamall/train_service_alert.py

@@ -0,0 +1,80 @@
+from typing import TypedDict, Unpack, Any
+
+from .base import BaseModel
+
+__all__ = [
+    "TrainServiceAlert",
+    "TrainServiceAlertManager",
+]
+
+
+class TrainServiceAlertPayload(TypedDict, total=False):
+    Status: str | int
+    Line: str
+    Direction: str
+    Stations: str
+    FreePublicBus: str
+    FreeMRTShuttle: str
+    MRTShuttleDirection: str
+    Message: str
+
+
+class TrainServiceAlert:
+    """Model representing an active transit service disruption alert on the rail network."""
+
+    def __init__(self, **kwargs: Unpack[TrainServiceAlertPayload]) -> None:
+        self.status: str = str(kwargs.get("Status", "Not Available"))
+        self.line: str = kwargs.get("Line", "Not Available")
+        self.direction: str = kwargs.get("Direction", "Not Available")
+        self.mrt_shuttle_direction: str = kwargs.get(
+            "MRTShuttleDirection", "Not Available"
+        )
+        self.message: str = kwargs.get("Message", "No Message")
+
+        self.stations: list[str] | str = self._parse_comma_string(
+            kwargs.get("Stations")
+        )
+        self.free_public_bus: list[str] | str = self._parse_comma_string(
+            kwargs.get("FreePublicBus")
+        )
+        self.free_mrt_shuttle: list[str] | str = self._parse_comma_string(
+            kwargs.get("FreeMRTShuttle")
+        )
+
+    def _parse_comma_string(self, raw_value: Any) -> list[str] | str:
+        """Safely parses comma-separated API string parameters into clean lists."""
+        if raw_value is None or str(raw_value).strip() == "":
+            return "Not Available"
+        return [item.strip() for item in str(raw_value).split(",") if item.strip()]
+
+
+class TrainServiceAlertManager(BaseModel):
+    """Orchestrates API bindings to monitor live rail transit network alert data streams."""
+
+    def get_alerts(self) -> list[TrainServiceAlert]:
+        """Fetches active train service disruption alerts.
+
+        Returns:
+            A list containing active TrainServiceAlert status tracking frameworks.
+        """
+        response = self.send("TrainServiceAlerts")
+        value_list = response.get("value")
+
+        if not isinstance(value_list, list):
+            raise ValueError(
+                "LTA DataMall API did not yield a valid data list layout for TrainServiceAlerts."
+            )
+
+        return [TrainServiceAlert(**alert) for alert in value_list]
+
+    async def async_get_alerts(self) -> list[TrainServiceAlert]:
+        """Asynchronously fetches active train service disruption alerts."""
+        response = await self.async_send("TrainServiceAlerts", params=None, json=None)
+        value_list = response.get("value")
+
+        if not isinstance(value_list, list):
+            raise ValueError(
+                "LTA DataMall API did not yield a valid data list layout for TrainServiceAlerts."
+            )
+
+        return [TrainServiceAlert(**alert) for alert in value_list]