Skip to content

zones_for_points

zones_for_points

zones_for_points(points: DataFrame | GeoDataFrame, zones: GeoDataFrame, *, predicate: str = 'within', columns: list[str] | None = None) -> GeoDataFrame

Tag each point (station / vehicle) with the geofencing zone(s) that contain it.

A spatial join, e.g. "which stations sit inside a no-parking zone?". Points outside every zone keep null zone columns (left join). Requires the [geo] extra.

Parameters:

Name Type Description Default
points DataFrame or GeoDataFrame

Points with lat/lon (a plain frame is promoted to a GeoDataFrame).

required
zones GeoDataFrame required
predicate str

Spatial predicate (within / intersects).

"within"
columns list of str

Zone attribute columns to attach (default: zone_id, name, ride_allowed, ride_through_allowed, maximum_speed_kph, station_parking).

None
See Also

zone_area_km2 : Area of each zone. to_canonical_geofencing : Parse the zones first.

Source code in src/gbfs_toolkit/spatial/geofencing.py
def zones_for_points(
    points: pd.DataFrame | gpd.GeoDataFrame,
    zones: gpd.GeoDataFrame,
    *,
    predicate: str = "within",
    columns: list[str] | None = None,
) -> gpd.GeoDataFrame:
    """Tag each point (station / vehicle) with the geofencing zone(s) that contain it.

    A spatial join, e.g. "which stations sit inside a no-parking zone?". Points outside
    every zone keep null zone columns (left join). Requires the ``[geo]`` extra.

    Parameters
    ----------
    points : pandas.DataFrame or geopandas.GeoDataFrame
        Points with ``lat``/``lon`` (a plain frame is promoted to a GeoDataFrame).
    zones : geopandas.GeoDataFrame
        Output of [`to_canonical_geofencing`][gbfs_toolkit.to_canonical_geofencing].
    predicate : str, default "within"
        Spatial predicate (``within`` / ``intersects``).
    columns : list of str, optional
        Zone attribute columns to attach (default: ``zone_id, name, ride_allowed,
        ride_through_allowed, maximum_speed_kph, station_parking``).

    See Also
    --------
    [`zone_area_km2`][gbfs_toolkit.zone_area_km2] : Area of each zone.
    [`to_canonical_geofencing`][gbfs_toolkit.to_canonical_geofencing] : Parse the zones first.
    """
    gpd, _ = _require_geo()
    from gbfs_toolkit.spatial.geometry import to_gdf

    pts = points if hasattr(points, "geometry") else to_gdf(points)
    attrs = columns or [
        "zone_id",
        "name",
        "ride_allowed",
        "ride_through_allowed",
        "maximum_speed_kph",
        "station_parking",
    ]
    attrs = [c for c in attrs if c in zones.columns]
    right = zones[[*attrs, "geometry"]].rename(columns={"name": "zone_name"})
    joined = gpd.sjoin(pts, right, how="left", predicate=predicate)
    return joined.drop(columns=[c for c in ("index_right",) if c in joined.columns])