Skip to content

to_canonical_station_info

to_canonical_station_info

to_canonical_station_info(raw: dict, *, system_id: str, gbfs_version: str = '2.x', station_type: str | None = None) -> DataFrame

Parse a station_information.json document into a canonical frame.

Parameters:

Name Type Description Default
raw dict

The parsed JSON of station_information (the full document, i.e. {"data": {"stations": [...]}, ...}, or just the data mapping).

required
system_id str

Identifier to stamp on every row.

required
gbfs_version str

Used only for the _name localisation heuristic and provenance.

"2.x"
station_type str

If given, force this type on all stations (overrides inference).

None

Returns:

Type Description
DataFrame

Canonical station-information frame (STATION_INFO_COLUMNS).

See Also

to_canonical_station_status : The matching live-status parser. GBFSFeed : The feed that calls these parsers.

Source code in src/gbfs_toolkit/io/normalize.py
def to_canonical_station_info(
    raw: dict,
    *,
    system_id: str,
    gbfs_version: str = "2.x",
    station_type: str | None = None,
) -> pd.DataFrame:
    """Parse a ``station_information.json`` document into a canonical frame.

    Parameters
    ----------
    raw : dict
        The parsed JSON of ``station_information`` (the full document, i.e.
        ``{"data": {"stations": [...]}, ...}``, or just the ``data`` mapping).
    system_id : str
        Identifier to stamp on every row.
    gbfs_version : str, default "2.x"
        Used only for the ``_name`` localisation heuristic and provenance.
    station_type : str, optional
        If given, force this type on all stations (overrides inference).

    Returns
    -------
    pandas.DataFrame
        Canonical station-information frame (`STATION_INFO_COLUMNS`).

    See Also
    --------
    [`to_canonical_station_status`][gbfs_toolkit.to_canonical_station_status] : The matching live-status parser.
    [`GBFSFeed`][gbfs_toolkit.GBFSFeed] : The feed that calls these parsers.
    """
    data = raw.get("data", raw)
    stations = _records(data, "stations")
    rows = []
    for s in stations:
        rows.append(
            {
                "system_id": system_id,
                "station_id": str(s.get("station_id")),
                "name": _name(s.get("name")),
                "lat": s.get("lat"),
                "lon": s.get("lon"),
                "capacity": s.get("capacity"),
                "station_type": station_type or _infer_station_type(s),
                "is_virtual_station": bool(s.get("is_virtual_station", False)),
                "region_id": s.get("region_id"),
            }
        )
    df = pd.DataFrame(rows, columns=STATION_INFO_COLUMNS)
    for col in ("lat", "lon", "capacity"):
        df[col] = pd.to_numeric(df[col], errors="coerce")
    df["region_id"] = df["region_id"].astype("string")  # join key, see to_canonical_system_regions
    return df