Getting started¶
Requirements¶
gbfs-toolkit supports Python 3.10 and later. The core has a deliberately small dependency
footprint (numpy, scipy and pandas only), so it installs cleanly into a constrained research
environment. Heavier capabilities are isolated behind optional extras and lazy imports, so the
core never pulls in geopandas, pyarrow or scikit-learn unless you ask for them.
Installation¶
pip install gbfs-toolkit # core only
pip install "gbfs-toolkit[fetch,parquet]" # a typical collection setup
pip install "gbfs-toolkit[fetch,parquet,cluster,geo,osm,dtw]" # everything
From a local clone, for development:
Extras matrix¶
Each extra unlocks one functional area. Installing a function's feature without its extra raises a clear error naming the missing package, so an environment never fails silently.
| Extra | Installs | Unlocks |
|---|---|---|
| (core) | numpy, scipy, pandas | Canonical data model, cross-version normalisation, static audit (A1–A7), CLI |
[fetch] |
requests | GBFSFeed, catalogue discovery, fetch_multiple, conditional GET, polite sessions |
[parquet] |
pyarrow | Longitudinal data lake: append_to_parquet, build_availability_panel, calculate_net_flow, manifests |
[cluster] |
scikit-learn | Spatial, spectral and diurnal-profile clustering |
[dtw] |
tslearn | Shape-aware diurnal clustering (method="dtw") |
[cli] |
rich, tqdm | Coloured gbfs audit tables and fetch_multiple(progress=True) bars (plain text and logging without it) |
[geo] |
geopandas | Geofencing zones, point-in-zone joins, equal-area density, to_gdf |
[osm] |
geopandas | Station surroundings, features_within, station_surroundings |
Verify the installation¶
import gbfs_toolkit as gb
gb.show_versions() # environment and dependency report, useful in bug reports
Quickstart: audit a bundled feed offline¶
The package ships a small, deterministic GBFS snapshot of central Paris for docs, doctests and offline tests. No network access is required.
import gbfs_toolkit as gb
info, status = gb.load_example() # canonical (station_info, station_status)
verdict = gb.audit_static(info) # A1–A7 verdict, one row per station
clean = info[~verdict["flagged"].to_numpy()] # keep the trustworthy stations
av = gb.join_availability(info, status) # bikes and docks per station
av["occupancy"] = gb.occupancy(av) # bikes / (bikes + docks), NaN-safe
Every public function is also a .gbfs accessor method and is pure, so method chaining and
df.pipe(...) both work:
Quickstart: from your own feed¶
import json
import gbfs_toolkit as gb
raw = json.load(open("station_information.json"))
stations = gb.to_canonical_station_info(raw, system_id="velib") # version-independent frame
verdict = gb.audit_static(stations) # A1–A7 per station
Command line¶
The CLI is the semantic counterpart to the syntactic gbfs-validator:
It prints a coloured table when rich is installed (pip install gbfs-toolkit[cli]) and the
output is an interactive terminal, and plain text otherwise. For pipelines, --json emits a
machine-readable summary, and --a7-scope all reproduces the gbfs-audit-catalogue verdicts:
Reproducibility¶
For a study that must be reproducible, pin the whole environment, not just gbfs-toolkit. The
audit thresholds and the canonical schema are frozen under semantic versioning, so a pinned version
reproduces the same verdicts.
pip install "gbfs-toolkit==1.1.0"
pip freeze > requirements.lock # or use a Poetry / uv / conda lock file
Record the lock file alongside your analysis. When you deposit a collected dataset, also record its
provenance with generate_manifest(lake_dir) and quantify gaps with coverage_report(panel), so a
reviewer can verify the data were frozen as described.
Geospatial extras
The [geo] and [osm] extras install geopandas, which pulls in compiled geospatial
libraries (GEOS, PROJ, GDAL). On most platforms the wheels install without a compiler, but on
constrained or ARM environments a conda-based install of geopandas is the most reliable path.
The core audit needs none of this.
Next steps¶
- Feature overview: the full walkthrough of ingestion, the data lake, clustering, statistics, geofencing and fleet reconciliation.
- Examples: runnable end-to-end scripts, plus a fully offline quickstart notebook.
- Methodology: the audit thresholds and the limits of what the toolkit can claim.
- Data model: the canonical schema contract and its dtype guarantees.