Skip to content

to_canonical_system_regions

to_canonical_system_regions

to_canonical_system_regions(raw: dict, *, system_id: str) -> DataFrame

Parse system_regions.json into a canonical region_id → name lookup.

Resolves the region_id foreign key carried on stations, so large multi-region networks can be subset or aggregated by region. Returns SYSTEM_REGION_COLUMNS.

See Also

to_canonical_system_information : The matching system-information parser.

Source code in src/gbfs_toolkit/io/normalize.py
def to_canonical_system_regions(raw: dict, *, system_id: str) -> pd.DataFrame:
    """Parse ``system_regions.json`` into a canonical ``region_id → name`` lookup.

    Resolves the ``region_id`` foreign key carried on stations, so large multi-region
    networks can be subset or aggregated by region. Returns
    `SYSTEM_REGION_COLUMNS`.

    See Also
    --------
    [`to_canonical_system_information`][gbfs_toolkit.to_canonical_system_information] : The matching system-information parser.
    """
    data = raw.get("data", raw)
    regions = _records(data, "regions")
    rows = [
        {
            "system_id": system_id,
            "region_id": str(r.get("region_id")),
            "name": _name(r.get("name")),
        }
        for r in regions
    ]
    df = pd.DataFrame(rows, columns=SYSTEM_REGION_COLUMNS)
    df["region_id"] = df["region_id"].astype("string")  # join key, see to_canonical_station_info
    return df