Feature overview¶
The full walkthrough of the toolkit beyond the quickstart: daily ergonomics, the longitudinal data lake, station clustering, descriptive and spatial statistics, multimodal links, station surroundings, geofencing, fleet reconciliation, and polite scraping with provenance.
Daily ergonomics¶
import gbfs_toolkit as gb
# discover by city (you rarely know the system_id)
cat = gb.systems_catalog()
paris = gb.filter_catalog(cat, country_code="FR", city="Paris")
feed = gb.GBFSFeed.from_url(url)
feed.summary() # one-glance card: stations, bikes, staleness, version
avail = feed.availability() # bikes/docks + name/coords/capacity, one frame
avail["state"] = gb.station_state(avail) # empty / full / disabled / normal
problems = gb.audit_dynamic(avail) # negative counts, over-capacity, stale
near = gb.find_nearest_stations(48.85, 2.35, feed.station_information(), k=3)
# many systems at once (threaded), broken feeds isolated as Exceptions
feeds = gb.fetch_multiple(["velib", "bixi", "lyon"], max_workers=5)
Longitudinal data lake¶
Turn a stream of snapshots into an analysis-ready panel. The library owns the
formatting / dedup / I/O; your orchestrator (cron, Airflow, and similar) owns the polling loop.
Requires the optional [parquet] extra (pyarrow).
import gbfs_toolkit as gb
# in your poller (every N minutes):
gb.append_to_parquet(feed.station_status(), "lake/") # Hive-partitioned by system_id/date
# in your analysis:
panel = gb.build_availability_panel("lake/", system_id="velib",
start_time="2026-06-01", resample_freq="5min")
flow = gb.calculate_net_flow(panel) # Δ bikes/station per poll (observed flow only)
build_availability_panel filters partitions before loading (memory-bounded),
de-duplicates redundant polls (same station_id + last_reported), and optionally
resamples each station to a fixed cadence.
Station clustering ([cluster])¶
Three lenses on "which stations belong together": spatial, topological, and behavioural.
gb.cluster_spatial(info, method="hdbscan") # density zones (projected metres)
gb.cluster_spectral(info, k=6) # network/topology groups
gb.cluster_diurnal_profiles(panel, n_clusters=4) # daily-rhythm typologies
cluster_diurnal_profiles turns the longitudinal panel into station typologies,
for example "morning commuter origin" (full at night, empty by day) versus "recreational", from each
station's 24-hour occupancy profile (robust to irregular sampling). Available options include
auto-k by silhouette, shape clustering (normalize="zscore"), soft GMM, DTW
(method="dtw", extra [dtw]), and weekday/weekend split. label_diurnal_typology
turns clusters into named types. This analysis is a primary use of the data lake.
Multimodal: bikeshare ↔ transit¶
stops = pd.read_csv("gtfs/stops.txt") # bring your own GTFS stops
linked = gb.link_transit_stops(info, stops, radius_m=200)
feeders = linked[linked["is_transit_feeder"]] # first/last-mile docks near rail/bus
Pure spatial proximity on GeoKDTree (no transit API, no schedules): is_transit_feeder,
nearest_stop_dist_m, n_transit_within.
Station surroundings: what is around each dock ([osm])¶
# generic "what's nearby", works for any point dataset (POIs, shops, …)
gb.features_within(info, pois, radius_m=300, category_col="amenity") # n_within, n_cafe, …
# bring your own OSM frame (fetch it yourself, e.g. osmnx.features_from_point)
# one-shot context: transit feeders + OSM features, in one frame
ctx = gb.station_surroundings(info, transit=stops, osm=osm_gdf, radius_m=300)
The radius summarisation (counts, per-category breakdown, and nearest distance) is the durable, tested core. Data acquisition follows a Bring Your Own GeoDataFrame model, so the library never depends on a live Overpass endpoint. Routing and isochrones stay out of scope (use OSMnx / pandana).
Descriptive stats: the bikeshare describe()¶
gb.system_profile(av) # stations, capacity, occupancy, % empty/full/…
gb.compare_systems({"velib": av1, "bixi": av2}) # one comparison row per city
gb.concentration_metrics(info) # capacity Gini + top-decile hub share (equity)
gb.coverage_stats(info, zones=zones) # density, nearest-neighbour, Clark–Evans dispersion
gb.availability_stats(panel) # per-station: occupancy, peak hour, volatility
Standard spatial / inequality algorithms (numpy/scipy only, deterministic):
gb.morans_i(info, "occupancy") # spatial autocorrelation (+ z-score / p-value)
gb.ripley_k(info, radii=[100, 250, 500]) # multi-scale clustering: L>0 clustered, <0 dispersed
gb.lorenz_curve(info) # inequality curve to plot (Gini/Theil in concentration_metrics)
These produce readable, comparable summaries that are strictly descriptive (no OD/trip inference). system_profile
is a one-glance numeric card of a snapshot. concentration_metrics is an equity lens (kept
outside the published A1–A7 audit, since it is a metric and not a quality verdict).
availability_stats turns a longitudinal panel into per-station scalars (pass a target_tz
panel for local-time peaks).
Fleet reconciliation: where the bikes actually are¶
tally = gb.reconcile_fleet_state(status, vehicles) # or feed.reconcile_fleet()
tally["total_deployed"] # on the street: stations + free-floating, overlap excluded
tally["total_rentable"] # available in stations + available free-floating
tally["double_count_avoided"] # vehicles a naive sum would have counted twice
GBFS reports the same fleet twice: aggregate docked counts in station_status and
individual units (some parked at stations) in vehicle_status. Naively adding them
double-counts every vehicle sitting at a dock. The reconciler excludes station-parked
vehicles from the deployed total and surfaces the overlap instead of hiding it.
Geofencing / service areas ([geo])¶
zones = gb.to_canonical_geofencing(raw, system_id="lime") # GeoDataFrame of operator polygons
tagged = gb.zones_for_points(info, zones) # which zone each station sits in
density = len(info) / gb.zone_area_km2(zones).sum() # bikes per km² of *real* service area
no_park = tagged[tagged["station_parking"] == False] # stations in park-restricted zones
For free-floating / hybrid systems the real footprint is the operator's polygons, not a
convex hull of stations. to_canonical_geofencing parses geofencing_zones.json (v2.x
ride_allowed and v3.x ride_start/ride_end_allowed reconciled), zones_for_points is the
point-in-zone spatial join, and zone_area_km2 reprojects to an equal-area CRS so density is
metric and latitude-comparable. The full per-vehicle-type rules list is preserved.
Polite scraping & provenance (research-grade)¶
session = gb.build_session() # pooled, retry/backoff on 429/5xx (default in fetch_multiple)
resp = gb.fetch_feed_json(url, etag=prev_etag) # conditional GET; raises GBFSNotModified on HTTP 304
...
gb.coverage_report(panel, expected_freq="5min") # per-station uptime / longest gap (no imputation)
gb.generate_manifest("lake/") # SHA-256 per partition + summary → cite on Zenodo
Built for scrapers that run for months: retries/backoff, conditional GETs (skip unchanged
snapshots), an offline catalogue cache, a GBFSError exception hierarchy, and provenance tools
so a dataset is citable and verifiable. Missing data stays missing: coverage_report
quantifies it rather than imputing.