Skip to content

resolve

resolve

resolve(system_id: str, catalog: DataFrame) -> dict

Resolve a system's discovery endpoint from a loaded catalogue.

Returns a dict with at least system_id, name, country_code and auto_discovery_url (the gbfs.json). Raises KeyError if not found.

See Also

systems_catalog : The catalogue this looks up. parse_discovery : Parse the resolved discovery document.

Source code in src/gbfs_toolkit/io/catalog.py
def resolve(system_id: str, catalog: pd.DataFrame) -> dict:
    """Resolve a system's discovery endpoint from a loaded catalogue.

    Returns a dict with at least ``system_id``, ``name``, ``country_code`` and
    ``auto_discovery_url`` (the ``gbfs.json``). Raises ``KeyError`` if not found.

    See Also
    --------
    [`systems_catalog`][gbfs_toolkit.systems_catalog] : The catalogue this looks up.
    [`parse_discovery`][gbfs_toolkit.parse_discovery] : Parse the resolved discovery document.
    """
    id_col = "system_id" if "system_id" in catalog.columns else catalog.columns[0]
    # Prefer the GBFS auto-discovery endpoint; only fall back to a bare ``url``
    # column. The MobilityData export ships both an operator-website ``url`` and
    # an ``auto-discovery_url``; resolving to the website fetches the homepage
    # instead of ``gbfs.json``, so auto-discovery must win regardless of order.
    url_col = next((c for c in catalog.columns if "auto" in c and "discovery" in c), None) or next(
        (c for c in catalog.columns if c == "url"), None
    )
    hit = catalog[catalog[id_col].astype(str).str.lower() == str(system_id).lower()]
    if hit.empty:
        raise GBFSDiscoveryError(f"system_id {system_id!r} not found in catalogue")
    row = hit.iloc[0]
    return {
        "system_id": str(row[id_col]),
        "name": row.get("name"),
        "country_code": row.get("country_code"),
        "auto_discovery_url": row.get(url_col) if url_col else None,
    }