bolster.data_sources.translink.stops

Translink stop metadata — lookup table from Open Data NI ATCO-CIF timetable zips.

Parses QL (stop name) and QB (stop location) records from the three Translink ATCO-CIF zip archives published on Open Data NI:

Metro & Glider (metro-glider-*.zip)

Ulsterbus/GoldLine (ulb-gle-*.zip)

Each zip contains one or more .cif files in Irish National Grid (ING) / OSGB coordinate system (Airy 1830 Modified ellipsoid, Transverse Mercator). Coordinates are converted to WGS84 (EPSG:4326) using the standard ING reverse projection.

The resulting lookup table maps NaPTAN ATCOCode (700000xxxxxx) to:

name : stop name as published in the CIF

easting : ING easting (integer metres)

northing : ING northing (integer metres)

latitude : WGS84 latitude (degrees)

longitude : WGS84 longitude (degrees)

The table is cached in memory after the first call. Pass force_refresh=True to re-download the source zips.

Example

>>> lookup = get_stop_lookup()
>>> lookup["700000001661"]["name"]
'Victoria Square Victoria Street'
>>> abs(lookup["700000001661"]["latitude"] - 54.595) < 0.01
True

Attributes

logger

Functions

`get_stop_lookup`([force_refresh])	Return the NaPTAN ATCOCode → stop metadata lookup table.
`resolve_stop_name`(atco_code[, fallback])	Return a human-readable name for a NaPTAN ATCOCode.
`find_stop`(query)	Search for stops by name using the Translink locationApi.
`get_stop_dataframe`([force_refresh])	Return the full stop lookup as a DataFrame.

Module Contents

bolster.data_sources.translink.stops.logger[source]

bolster.data_sources.translink.stops.get_stop_lookup(force_refresh=False)[source]

Return the NaPTAN ATCOCode → stop metadata lookup table.

The table is built on first call and cached in memory for the lifetime of the process. The underlying zip files are cached on disk for one week.

Parameters:

force_refresh (bool) – Re-download source zips and rebuild the lookup.

Returns:

name (str): Stop name from the CIF
easting (int): ING easting in metres
northing (int): ING northing in metres
latitude (float): WGS84 latitude
longitude (float): WGS84 longitude

Return type:

Dict mapping ATCOCode (e.g. "700000001661") to a dict with keys

Raises:

TranslinkDataNotFoundError – If the source zips cannot be downloaded.
TranslinkValidationError – If the resulting table is implausibly small.

bolster.data_sources.translink.stops.resolve_stop_name(atco_code, fallback=True)[source]

Return a human-readable name for a NaPTAN ATCOCode.

Looks up the code in the CIF-derived table first. If not found and fallback is True, queries the Translink locationApi live.

Parameters:

atco_code (str) – NaPTAN ATCOCode, e.g. "700000014482".
fallback (bool) – If True, attempt a live API lookup for unknown codes.

Returns:

Stop name string, or None if not resolvable.

Return type:

str | None

bolster.data_sources.translink.stops.find_stop(query)[source]

Search for stops by name using the Translink locationApi.

Parameters:: query (str) – Partial or full stop name, e.g. "Cambria Street".
Returns:: id (Translink internal StopId), name, location_type.
Return type:: List of dicts, each with keys
Raises:: TranslinkDataNotFoundError – If the API request fails.

bolster.data_sources.translink.stops.get_stop_dataframe(force_refresh=False)[source]

Return the full stop lookup as a DataFrame.

Columns: atco_code, name, easting, northing, latitude, longitude.

Parameters:: force_refresh (bool) – Re-download and rebuild the stop table.
Returns:: DataFrame with one row per stop, indexed by atco_code.
Return type:: pandas.DataFrame