bolster.data_sources.translink.vehicles

Translink live vehicle positions from the VMI (Vehicle Monitoring Interface) feed.

The VMI feed at vpos.translinkniplanner.co.uk/velocmap/vmi/VMI is an undocumented, unauthenticated JSON endpoint operated by Vix Technology on behalf of Translink. It returns a snapshot of all active vehicles across Ulsterbus, Metro, and Glider services, updated approximately every 66 seconds.

Key notes on the feed: - X / Y are strings (longitude / latitude WGS84), not floats. - JourneyIdentifier contains #!ADD!#vixvm_new# suffixes — strip from #. - IsAtStop only appears when True (sparse field). - Delay is in seconds (negative = early). - Operator code TM in VehicleIdentifier denotes Metro buses. - CurrentStop / NextStop are NaPTAN ATCOCodes (700000xxxxxx).

Example

>>> vdf = get_live_vehicles()
>>> {"vehicle_id", "line", "latitude", "longitude"}.issubset(vdf.columns)
True
>>> len(vdf) > 0
True

Attributes

logger

Functions

`get_live_vehicles`([line, operator, enrich_stops])	Return a snapshot of live vehicle positions from the Translink VMI feed.
`validate_vehicles`(df)	Validate a live vehicles DataFrame.

Module Contents

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

bolster.data_sources.translink.vehicles.get_live_vehicles(line=None, operator=None, enrich_stops=False)[source]

Return a snapshot of live vehicle positions from the Translink VMI feed.

Parameters:

line (str | None) – Optional line filter, case-insensitive (e.g. "11E" or "G1").
operator (str | None) – Optional operator filter, case-insensitive. Accepts canonical codes ("MET") or VMI codes ("TM"). Both map to Metro.
enrich_stops (bool) – If True, resolve current_stop / next_stop ATCOCodes to human-readable names. Requires building the stop lookup table on first call (~1.3 MB download).

Returns:

id, vehicle_id, operator, operator_raw, line, direction, journey_id, day_of_operation, longitude, latitude, longitude_prev, latitude_prev, timestamp (tz-aware), timestamp_prev (tz-aware), delay_seconds (Int64, negative = early), current_stop, next_stop, is_at_stop (bool), realtime_available (bool), mot_code (Int64).

Return type:

DataFrame with one row per active vehicle. Columns

Raises:

TranslinkDataNotFoundError – If the VMI feed cannot be reached.
TranslinkValidationError – If the response is malformed.

Example

>>> vdf = get_live_vehicles(line="11E")
>>> all(vdf["line"].str.upper() == "11E")
True

bolster.data_sources.translink.vehicles.validate_vehicles(df)[source]

Validate a live vehicles DataFrame.

Parameters:: df (pandas.DataFrame) – DataFrame as returned by get_live_vehicles().
Returns:: True if validation passes.
Raises:: TranslinkValidationError – If required columns are missing or coordinates are invalid.
Return type:: bool