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