API reference¶
Every public object, generated from gbfs_toolkit.__all__ (so this catalogue is always complete). Use the search bar to jump straight to a function, or browse by theme below.
Start with the data model
Every function in this library consumes or returns the canonical, tz-aware UTC pandas frames described in Data model & schemas. Read it first: the column names and dtypes are the contract these functions rely on.
Audit (A1–A7)¶
| Function | Summary |
|---|---|
audit_catalogue |
Fetch and audit many systems with one call. |
audit_dynamic |
Logic checks on a live availability frame. |
audit_frames |
Unified semantic audit on canonical frames: static (A1–A7) and, if given, dynamic (D1–D3). |
audit_sensitivity |
One-at-a-time threshold sensitivity of the A1–A7 audit. |
audit_static |
Run the A1–A7 semantic audit on a canonical station-information frame. |
capacity_convention |
Label each system's capacity-field publication convention. |
classify_from_vehicle_types |
Feed-intrinsic car-sharing classification from GBFS v3 vehicle_types. |
classify_from_virtual_station |
Feed-intrinsic free-floating tagging from GBFS v3 is_virtual_station. |
drop_flagged |
The analysis-ready subset: stations that pass the static A1–A7 audit, in one call. |
flag_rate_ci |
System-level flag rate per class with a cluster-bootstrap confidence interval. |
flag_sentinel_coordinates |
Boolean mask of stations sitting on the (0, 0) null-island sentinel. |
overcapacity_ratio |
Per-system A3 over-capacity ratio from declared station capacity. |
reclassify_overcapacity |
Relabel over-capacity systems as free_floating (the audit protocol's S3 step). |
vehicle_id_persistence |
Characterise whether a feed rotates or persists its vehicle_id values. |
Analytics¶
| Function | Summary |
|---|---|
aliasing_vulnerability |
Per-station risk that the polling cadence misses short-timescale dynamics. |
availability_stats |
Per-station longitudinal statistics from an availability panel. |
availability_synchrony |
Pairwise correlation of station availability series: a functional synchrony network. |
block_bootstrap_ci |
Moving-block bootstrap confidence interval for a statistic of a dependent series. |
boundary_stress |
Per-station share of time near empty or near full, not just at the boundary. |
capacity_utilization |
Add utilization_rate = available bikes / station capacity. |
censored_time_ratio |
Fraction of station-time at a saturation boundary, where demand is unobservable. |
cluster_diurnal_profiles |
Cluster stations by their daily rhythm (the crown jewel of the longitudinal layer). |
cluster_spatial |
Group stations into spatial zones by physical proximity. |
cluster_spectral |
Topological clustering: geographic kNN affinity → Laplacian spectrum → k-means. |
cohen_kappa |
Cohen's kappa between two raters over paired nominal labels. |
compare_systems |
Stack system_profile across many systems into a comparison table. |
concentration_metrics |
How concentrated is capacity across stations? An equity / coverage lens. |
cumulative_imbalance |
Per-station cumulative net flow (drift) since each period's start. |
cyclical_time_features |
Encode calendar fields as (sin, cos) pairs: the one everyone re-implements. |
detect_ghost_vehicles |
Flag immobile ("ghost") vehicles from a longitudinal vehicle panel. |
diurnal_bimodality |
Sarle's bimodality coefficient of each station's diurnal profile. |
diurnal_profiles |
Build each station's mean occupancy profile by hour of day. |
diurnal_summary_stats |
Hour-of-day summary of a quantity: mean, median and robust P5/P95 bands. |
docking_pressure |
Per-observation docking saturation tension: typical inflow over free docks. |
dynamic_gini_index |
Gini coefficient of available bikes across stations, as a time series. |
ebikes |
Electric vehicles only (any electric* propulsion), with their type attributes joined. |
effective_sample_size |
Autocorrelation-adjusted effective sample size of a 1-D series. |
filter_vehicles |
Resolve vehicle types then keep only matching vehicles: "where are the X?" in one call. |
fleet_turnover_proxy |
System-level turnover proxy: half the summed absolute flow per fleet vehicle, per period. |
flow_asymmetry_ratio |
Per-station ratio of total inflow to total outflow. |
format_paper_summary |
Render a profile as a publication-ready Markdown or LaTeX table. |
join_availability |
Join a status snapshot onto the station inventory: the analysis-ready availability frame. |
join_exogenous_timeseries |
Align an external time series (weather, traffic, air quality) onto the panel. |
join_pricing |
Resolve pricing_plan_id → plan name / price / currency onto a vehicles frame. |
join_vehicle_types |
Resolve vehicle_type_id → form factor / propulsion / range onto a vehicles frame. |
krippendorff_alpha |
Krippendorff's alpha for nominal data. |
label_diurnal_typology |
Assign a human-readable behavioural type to each station from its 24-h profile. |
lorenz_curve |
Lorenz-curve points for plotting capacity inequality. |
network_changes |
Diff two station inventories: how the network itself changed between two dates. |
occupancy |
Occupancy ratio: bikes / (bikes + docks) per station. |
outage_survival |
Empirical survival function of outage durations: the time-to-recovery view. |
palma_ratio |
Palma ratio: the top-10% share over the bottom-40% share. |
rebalancing_tension |
Minimum-work spatial rebalancing tension per timestamp, in bike-kilometres. |
reconcile_fleet_state |
Reconcile docked and free-floating feeds into one labelled fleet tally. |
service_reliability_index |
Empirical level-of-service probability per station and time-of-day. |
station_outage_rates |
Per-station fraction of time empty (stockout) and full (saturation). |
station_state |
Classify each station as disabled / virtual / empty / full / normal. |
system_profile |
A one-glance numeric profile of one availability snapshot: the bikeshare describe(). |
temporal_autocorrelation |
Per-station autocorrelation of availability at fixed lags (hour, day, week). |
temporal_concentration |
Per-station temporal peaking: the Gini of activity across time-of-day bins. |
temporal_context_features |
Add standard calendar context columns for descriptive temporal analysis. |
theil_index |
Theil's T inequality index, optionally decomposed between and within groups. |
vehicle_idle_time |
Fraction of the fleet that has not moved for threshold_hours, as a time series. |
wilson_interval |
Wilson score interval for a binomial proportion (default 95%). |
Spatial¶
| Function | Summary |
|---|---|
coverage_stats |
Spatial coverage of a station network: density and dispersion. |
enrich_with_osm |
Count nearby OSM features around each station (Bring Your Own GeoDataFrame). |
fdr_adjust |
Multiple-testing correction of a vector of p-values (Benjamini-Hochberg). |
features_within |
Summarise the features around each point: the generic "what's nearby" primitive. |
filter_by_bbox |
Keep only the rows inside a lon/lat bounding box. |
find_nearest_stations |
Return the k stations closest to (lat, lon), with a distance column. |
GeoKDTree |
A great-circle k-NN / radius index over lat/lon points (EPSG:4326). |
haversine_m |
Vectorised great-circle distance in metres between two coordinate arrays. |
link_transit_stops |
Attach transit-proximity metrics to each station. |
local_morans_i |
Local Moran's I (LISA): per-station spatial-autocorrelation hotspots and cold spots. |
morans_i |
Global Moran's I: spatial autocorrelation of value_col across stations. |
ripley_k |
Ripley's K / L: multi-scale clustering of station locations. |
spatial_center_of_mass |
Fleet centre of gravity over time: the weighted-mean station coordinate per period. |
spatial_entropy |
Shannon entropy of the free-floating fleet's spatial distribution over time. |
spatial_outage_redundancy |
Separate a station's local stockouts from systemic neighbourhood failures. |
station_surroundings |
One-shot "what's around each station": transit feeders + OSM features in a radius. |
stations_near |
For each external point, how many stations are nearby: the accessibility primitive. |
to_canonical_geofencing |
Parse a geofencing_zones.json document into a canonical GeoDataFrame. |
to_gdf |
Convert a frame with lat/lon columns to a GeoPandas GeoDataFrame (lazy import). |
to_geojson |
Export stations / zones to GeoJSON for QGIS, kepler.gl, etc. (data, not a map). |
two_step_fca |
Two-step floating catchment area (2SFCA) accessibility, a spatial-equity measure. |
zone_area_km2 |
Area of each zone in km², computed in an equal-area projection (not in degrees). |
zones_for_points |
Tag each point (station / vehicle) with the geofencing zone(s) that contain it. |
Ingestion & I/O¶
| Function | Summary |
|---|---|
add_local_time |
Add a local-time column to a panel, handling the index correctly. |
append_to_parquet |
Append a snapshot to a Hive-partitioned Parquet dataset (append-only, fast). |
audit_feed |
One-liner: A1–A7 semantic audit of a live feed. |
availability |
One-liner: live availability (bikes/docks + name/coords) from a gbfs.json URL. |
build_availability_panel |
Read a partitioned dataset into a tidy availability panel. |
build_session |
A pooled requests.Session with polite retry/backoff: the right default for scraping. |
calculate_net_flow |
Period-over-period change in available bikes per station. |
coverage_report |
Longitudinal coverage: quantify missingness before you model. |
detect_frozen_stations |
Flag "frozen" stations: a value stuck unchanged while the feed keeps updating. |
extract_snapshot_asof |
Extract the city's state at one instant: each station's last reading at or before T. |
FeedResponse |
FeedResponse(data, etag, last_modified) |
fetch_feed_json |
Conditionally fetch a feed, honouring HTTP caching: the polite way to poll. |
fetch_multiple |
Resolve and open many systems concurrently (threaded) for comparative studies. |
filter_catalog |
Filter the systems catalogue, because you know "Paris", not the system_id. |
flow_balance |
Per-station inflow / outflow split and source↔sink balance. |
GBFSFeed |
A friendly handle on one GBFS system: discover once, fetch tidy frames. |
generate_manifest |
A cryptographic manifest of a Parquet lake, for citable, reproducible datasets. |
insert_explicit_gaps |
Insert NaN rows where collection stalled, so plots show the outage honestly. |
normalize_operator |
Canonicalise an operator brand from a system id / name ("smovengo" → ``"Vélib' |
parse_discovery |
Parse a gbfs.json auto-discovery document → ({feed_name: url}, version). |
resample_panel |
Resample each station series onto a fixed time grid, carrying the last state forward. |
resolve |
Resolve a system's discovery endpoint from a loaded catalogue. |
stockout_episodes |
Discrete empty/full episodes per station: the service-quality view of a panel. |
systems_catalog |
Load the MobilityData systems catalogue, cached in-process and on disk. |
to_canonical_alerts |
Parse system_alerts.json into a canonical alerts frame. |
to_canonical_pricing_plans |
Parse system_pricing_plans.json into a canonical lookup table. |
to_canonical_station_info |
Parse a station_information.json document into a canonical frame. |
to_canonical_station_status |
Parse a station_status.json document into a canonical frame. |
to_canonical_station_vehicle_counts |
Melt per-vehicle-type availability from station_status into a long frame. |
to_canonical_system_information |
Parse system_information.json into a small dict of system metadata. |
to_canonical_system_regions |
Parse system_regions.json into a canonical region_id → name lookup. |
to_canonical_vehicle_types |
Parse vehicle_types.json into a canonical catalogue. |
to_canonical_vehicles |
Parse free_bike_status (2.x) or vehicle_status (3.x) into a canonical frame. |
to_wide_matrix |
Pivot a long panel into a time-by-station matrix. |
turnover |
Per-station activity proxy: summed absolute net flow per period. |
Interfaces¶
| Function | Summary |
|---|---|
load_example |
Return a small canonical (station_info, station_status) pair for examples. |
show_versions |
Print Python, OS and key dependency versions (the usual show_versions diagnostic). |
Core & schema¶
| Function | Summary |
|---|---|
__version__ |
str(object='') -> str |
AUDIT_FLAGS |
Built-in immutable sequence. |
coerce_schema |
Cast a frame's columns to the canonical dtypes for schema (nullable ints/bools, UTC). |
GBFSDiscoveryError |
A gbfs.json could not be parsed, or a required feed is absent. |
GBFSError |
Base class for every error raised by gbfs-toolkit. |
GBFSFetchError |
A network fetch failed (HTTP error, timeout, unreachable host). |
GBFSNotModified |
The server answered HTTP 304 Not Modified; skip re-ingesting this snapshot. |
GBFSValidationError |
Data does not satisfy the canonical schema or a documented invariant. |
models |
Canonical data model for GBFS feeds: the stable contract every other module |
require_columns |
Raise a didactic SchemaError if df is missing any of columns. |
RULES |
dict() -> new empty dictionary |
SchemaError |
Raised when a frame does not satisfy the canonical schema. |
SCHEMAS |
dict() -> new empty dictionary |
validate_schema |
Assert a frame still obeys a canonical schema, then return it (for chaining). |