Skip to content

to_canonical_geofencing

to_canonical_geofencing

to_canonical_geofencing(raw: dict, *, system_id: str, gbfs_version: str = '2.x') -> GeoDataFrame

Parse a geofencing_zones.json document into a canonical GeoDataFrame.

Returns one row per zone with a shapely geometry (EPSG:4326) and the columns of GEOFENCING_COLUMNS. The boolean/speed fields summarise each zone's default rule; the full per-vehicle-type rules list is preserved verbatim.

Parameters:

Name Type Description Default
raw dict

Parsed geofencing_zones document (full doc or its data mapping).

required
system_id str

Identifier stamped on every row.

required
See Also

zone_area_km2 : Area of the parsed zones. zones_for_points : Assign points to the parsed zones.

Source code in src/gbfs_toolkit/spatial/geofencing.py
def to_canonical_geofencing(
    raw: dict, *, system_id: str, gbfs_version: str = "2.x"
) -> gpd.GeoDataFrame:
    """Parse a ``geofencing_zones.json`` document into a canonical ``GeoDataFrame``.

    Returns one row per zone with a shapely geometry (EPSG:4326) and the columns of
    `GEOFENCING_COLUMNS`. The boolean/speed fields summarise each
    zone's *default* rule; the full per-vehicle-type ``rules`` list is preserved verbatim.

    Parameters
    ----------
    raw : dict
        Parsed ``geofencing_zones`` document (full doc or its ``data`` mapping).
    system_id : str
        Identifier stamped on every row.

    See Also
    --------
    [`zone_area_km2`][gbfs_toolkit.zone_area_km2] : Area of the parsed zones.
    [`zones_for_points`][gbfs_toolkit.zones_for_points] : Assign points to the parsed zones.
    """
    gpd, shape = _require_geo()
    data = raw.get("data", raw)
    gz = data.get("geofencing_zones", data) if isinstance(data, dict) else {}
    features = gz.get("features", []) if isinstance(gz, dict) else []

    rows, geoms = [], []
    for i, feat in enumerate(features):
        geom = feat.get("geometry")
        if not geom:
            continue
        props = feat.get("properties") or {}
        rules = props.get("rules") or []
        rule = _default_rule(rules)
        rows.append(
            {
                "system_id": system_id,
                "zone_id": str(props.get("name") or i),
                "name": props.get("name"),
                "ride_allowed": _ride_allowed(rule),
                "ride_through_allowed": rule.get("ride_through_allowed"),
                "maximum_speed_kph": rule.get("maximum_speed_kph"),
                "station_parking": rule.get("station_parking"),
                "rules": rules,
            }
        )
        geoms.append(shape(geom))

    if not rows:
        return gpd.GeoDataFrame(
            {c: pd.Series(dtype="object") for c in _NON_GEOM}, geometry=[], crs="EPSG:4326"
        )
    gdf = gpd.GeoDataFrame(rows, geometry=geoms, crs="EPSG:4326")
    return gdf[[*_NON_GEOM, "geometry"]]