Skip to content

to_canonical_station_status

to_canonical_station_status

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

Parse a station_status.json document into a canonical frame.

Returns STATION_STATUS_COLUMNS. fetched_at is a tz-aware UTC timestamp stamped on every row (defaults to now) for provenance.

See Also

to_canonical_station_info : The matching inventory parser. to_canonical_station_vehicle_counts : Per-type counts at the station.

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

    Returns `STATION_STATUS_COLUMNS`. ``fetched_at`` is a
    tz-aware UTC timestamp stamped on every row (defaults to *now*) for provenance.

    See Also
    --------
    [`to_canonical_station_info`][gbfs_toolkit.to_canonical_station_info] : The matching inventory parser.
    [`to_canonical_station_vehicle_counts`][gbfs_toolkit.to_canonical_station_vehicle_counts] : Per-type counts at the station.
    """
    fetched_at = fetched_at if fetched_at is not None else _now_utc()
    data = raw.get("data", raw)
    stations = _records(data, "stations")
    rows = [
        {
            "system_id": system_id,
            "station_id": str(s.get("station_id")),
            # GBFS 3.0 renamed num_bikes_available → num_vehicles_available; accept both.
            "num_bikes_available": (
                s["num_bikes_available"]
                if s.get("num_bikes_available") is not None
                else s.get("num_vehicles_available")
            ),
            # GBFS 3.0 also offers vehicle_docks_available alongside num_docks_available.
            "num_docks_available": (
                s["num_docks_available"]
                if s.get("num_docks_available") is not None
                else s.get("vehicle_docks_available")
            ),
            "is_renting": bool(s.get("is_renting", True)),
            "is_returning": bool(s.get("is_returning", True)),
            "is_installed": bool(s.get("is_installed", True)),
            "last_reported": _utc(s.get("last_reported")),
            "fetched_at": fetched_at,
            "gbfs_version": gbfs_version,
        }
        for s in stations
    ]
    df = pd.DataFrame(rows, columns=STATION_STATUS_COLUMNS)
    # Nullable extension dtypes so a later outer join (e.g. availability()) inserts
    # pd.NA without silently upcasting counts/flags to float and corrupting equality.
    for col in ("num_bikes_available", "num_docks_available"):
        df[col] = pd.to_numeric(df[col], errors="coerce").astype("Int64")
    for col in ("is_renting", "is_returning", "is_installed"):
        df[col] = df[col].astype("boolean")
    for col in ("last_reported", "fetched_at"):
        df[col] = pd.to_datetime(df[col], utc=True)
    return df