bolster.data_sources.translink.stops
====================================

.. py:module:: bolster.data_sources.translink.stops

.. autoapi-nested-parse::

   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.

   .. rubric:: Example

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



Attributes
----------

.. autoapisummary::

   bolster.data_sources.translink.stops.logger


Functions
---------

.. autoapisummary::

   bolster.data_sources.translink.stops.get_stop_lookup
   bolster.data_sources.translink.stops.resolve_stop_name
   bolster.data_sources.translink.stops.find_stop
   bolster.data_sources.translink.stops.get_stop_dataframe


Module Contents
---------------

.. py:data:: logger

.. py:function:: get_stop_lookup(force_refresh = False)

   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.

   :param force_refresh: 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
   :rtype: Dict mapping ``ATCOCode`` (e.g. ``"700000001661"``) to a dict with keys

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


.. py:function:: resolve_stop_name(atco_code, fallback = True)

   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.

   :param atco_code: NaPTAN ATCOCode, e.g. ``"700000014482"``.
   :param fallback: If True, attempt a live API lookup for unknown codes.

   :returns: Stop name string, or None if not resolvable.


.. py:function:: find_stop(query)

   Search for stops by name using the Translink locationApi.

   :param query: Partial or full stop name, e.g. ``"Cambria Street"``.

   :returns: ``id`` (Translink internal StopId), ``name``, ``location_type``.
   :rtype: List of dicts, each with keys

   :raises TranslinkDataNotFoundError: If the API request fails.


.. py:function:: get_stop_dataframe(force_refresh = False)

   Return the full stop lookup as a DataFrame.

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

   :param force_refresh: Re-download and rebuild the stop table.

   :returns: DataFrame with one row per stop, indexed by ``atco_code``.