Skip to content

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).