LTADataMallpy

A Python wrapper for the LTA DataMall API, providing typed, easy-to-use access to Singapore's public transport and traffic data: buses, trains, taxis, roads, active mobility, and geospatial layers.

Built on httpx, it ships with automatic pagination for endpoints returning more than 500 records, a persistent connection pool, and descriptive custom exceptions.

Features

• Single entry point: DataMall with transport, traffic, and geospatial namespaces
• Typed responses: every endpoint returns validated pydantic models (LtaResult[T] for lists), not raw dicts
• Automatic pagination ($skip handling) for long endpoints
• Persistent httpx.Client with a 30s timeout and explicit close_client()
• Custom exceptions with response status code, message, and timestamp
• Python >=3.10 (X | None syntax, built-in generics), fully typed (py.typed-style annotations throughout)

Installation

From PyPI

pip install lta-api-py

Getting an API key

1. Register at the LTA DataMall portal.
2. Create an account and request access to an API key.
3. Use the key as the api_key argument (or load it from an environment variable / .env file).

Quick start

from LTADataMallpy import DataMall
import os

dm = DataMall(api_key=os.getenv("LTA_API_KEY"))

# Transport data — typed pydantic models, not dicts
arrivals = dm.transport.bus.arrival.get_bus_arrival(stopcode="83111")
for service in arrivals.services:
    print(service.service_no, service.next_bus.estimated_arrival)

# Traffic data
speed_bands = dm.traffic.roads.get_traffic_speed_bands()
for band in speed_bands.value:
    print(band.road_name, band.speed_band)

Always close the client when you are done to release the connection pool:

from LTADataMallpy.helpers import close_client
# ... your requests ...
close_client()

API reference

Everything is imported from the top-level package LTADataMallpy.

Main entry point: DataMall

from LTADataMallpy import DataMall

dm = DataMall(api_key: str, accept: str | None = None)

Raises ValueError if api_key is empty or missing. Exposes three namespaces:

Transport

from LTADataMallpy import DataMall
dm = DataMall(API_KEY)
t = dm.transport

Traffic

dm = DataMall(API_KEY)
tr = dm.traffic

Geospatial

dm = DataMall(API_KEY)
G = dm.geospatial
G.get_geo_layer(id="LayerName")

LTA DataMall geospatial layers require a Token in the request header in addition to AccountKey. Pass the token as the accept argument (it is forwarded as the accept header value):

dm = DataMall(api_key=API_KEY, accept=YOUR_GEOSPATIAL_TOKEN)
data = dm.geospatial.get_geo_layer(id="factoryarea")

Classes to import directly

Each underlying class is importable on its own, taking (api_key, accept=None) unless noted:

from LTADataMallpy.Bus import Bus
from LTADataMallpy.Train import Train
from LTADataMallpy.Taxi import Taxi
from LTADataMallpy.Roads import Roads
from LTADataMallpy.Infra import Infra
from LTADataMallpy.ActiveMobility import ActiveMobility
from LTADataMallpy.Geo import Geospatial
from LTADataMallpy.subclasses import Transport, Traffic

Methods

Bus

Train

Taxi

Roads (traffic)

Infra (traffic)

ActiveMobility

Geospatial

Helpers

Low-level helpers live in LTADataMallpy.helpers and can be used for custom endpoint calls:

from LTADataMallpy.helpers import (
    build_headers,        # build the AccountKey/accept header dict from an API key
    build_url,            # join an endpoint to the DataMall base URL
    make_request,         # GET one page; raises custom errors in the helpers module
    make_paginated_request,  # fetch all pages, combining "value" lists
    create_client,        # lazily create/reuse the persistent httpx.Client
    close_client,         # close the persistent client (self-heals on next use)
)

Example of a custom call:

from LTADataMallpy.helpers import build_headers, build_url, make_request

headers = build_headers(API_KEY)
url = build_url("SomeEndpoint")
data = make_request(headers, url, params={"SomeParam": "value"})

Persistent client

• The shared httpx.Client is created lazily on the first request (with timeout=30.0) and reused for every call, keeping TCP/TLS connections alive.
• Call close_client() at the end of a script to free resources. It is safe to call mid-run: the next request transparently recreates the client.
• httpx.Client is thread-safe, so the client can be shared across threads.

Pagination

Endpoints marked Paginated above go through make_paginated_request, which automatically walks $skip in 500-record pages and merges every page's value list into a single response before it is validated into the model.

Error handling and debugging

make_request maps known HTTP statuses to descriptive exceptions (all in LTADataMallpy.helpers, subclasses of DataMallError):

Every DataMallError exposes .status_code and .detail (the API's error message when parseable) and stringifies as "{status_code} {detail}". Any other status passes through httpx.Response.raise_for_status().

from LTADataMallpy import DataMall
from LTADataMallpy.helpers import DataMallPermissionError, DataMallRateLimitError

dm = DataMall(api_key="invalid-key")

try:
    dm.transport.bus.arrival.get_bus_arrival("83111")
except DataMallPermissionError as e:
    print("Bad key:", e.status_code, e.detail)
except DataMallRateLimitError as e:
    print("Slow down:", e.status_code, e.detail)

Debugging tips

• 429 / rate limit: LTA enforces per-minute request quotas. Add backoff, or cache responses you fetch repeatedly.
• Timeout: the client uses a 30-second timeout; paginated calls to big datasets (e.g. BusRoutes, BusServices) can be slow on a cold connection.
• Check connectivity: confirm the key is active in the DataMall portal and that your network reaches datamall2.mytransport.sg.
• .env / secrets: load your key from an environment variable rather than hard-coding it. The .env file is git-ignored.

Development

uv sync --group dev       # install with dev extras (pytest, python-dotenv)
uv run pytest tests/      # full suite; hits the live API, needs LTADATAMALL_API_KEY in .env
uv build                  # build sdist + wheel into dist/
uvx twine check dist/*    # validate package metadata

Tests read LTADATAMALL_API_KEY from a .env file (git-ignored) or the environment; without it they skip. Requests are paced ~3s apart to respect LTA rate limits.

License

Apache License 2.0. See LICENSE.

Links

• Repository: https://github.com/Rayablepy/LTADataMallpy
• Issues: https://github.com/Rayablepy/LTADataMallpy/issues
• LTA DataMall: https://www.mytransport.sg/content/mytransport/home/dataMall.html