Skip to content

gbfs-toolkit

Research-grade ingestion and semantic quality audit for GBFS bike-share feeds.

Rohan Fossé1 and Gaël Pallares2

1 CESI Engineering School, Montpellier  ·  2 CESI LINEACT (EA 7527), Montpellier, France

PyPI Python CI License

GBFS bike-sharing shared mobility data quality semantic validation reproducibility open data

Abstract

gbfs-toolkit ingests GBFS bike-share feeds into a stable, version-independent data model and audits their semantic quality with the A1–A7 taxonomy of Fossé and Pallares. MobilityData's gbfs-validator checks that a feed is syntactically valid. This toolkit checks whether it is semantically trustworthy and analysis-ready, which is the part a study actually depends on. It consolidates ingestion, cross-version normalisation, and the published quality-audit pipeline into one tested, installable interface for reuse across shared-mobility research.

  • Getting started


    Install the core and only the extras you need, then audit a feed in a few lines.

    Installation and quickstart

  • Semantic audit


    The published static taxonomy (A1–A7) and the dynamic checks (D1–D3), with every threshold stated.

    Methodology

  • API reference


    Every public function, grouped by module and generated from the source docstrings.

    Reference

  • Cite this work


    BibTeX, ORCID identifiers, and provenance tooling for reproducible studies.

    Citing this work

Position in the GBFS ecosystem

gbfs-toolkit is the semantic counterpart to the syntactic validator, not a replacement for it. The two operate at different layers and answer different questions.

Aspect gbfs-validator (MobilityData) gbfs-toolkit (CESI LINEACT)
Validation layer Syntactic: JSON-schema conformance Semantic: analysis-readiness and plausibility
Question answered Is the feed well-formed GBFS? Can I trust each station for a study?
Granularity Feed and file Per-station verdict (A1–A7) and per-snapshot verdict (D1–D3)
Cross-version model Not applicable Canonical frames across GBFS 1.x, 2.x and 3.x
Spatial and temporal checks None Coordinates, perimeter, staleness, frozen sensors
Output Pass or fail with schema errors Tidy DataFrame of verdicts with explicit reasons
Scope Conformance Ingestion, audit, and longitudinal analysis

A feed can pass the syntactic validator and still carry placeholder capacities, phantom docks, transposed coordinates, or out-of-perimeter stations. Those are the defects the semantic audit is designed to surface.

Scope and limitations

What the toolkit does not do

gbfs-toolkit ingests, normalises, audits and summarises GBFS feeds. It deliberately does not perform origin-destination or trip inference, routing or isochrones, demand prediction, or imputation of missing data, and it ships no scheduler or daemon. Flow quantities are observed lower bounds, not trip counts (see the Methodology). These boundaries are by design: the toolkit returns tidy frames, and you bring the model and the map.

Install

pip install gbfs-toolkit

The core depends only on numpy, scipy and pandas. Optional capabilities live behind extras ([fetch], [parquet], [cluster], [geo], [osm], [dtw]). See Getting started for the full extras matrix.

Quickstart

import gbfs_toolkit as gb

info, status = gb.load_example()      # bundled sample, no network needed
clean = info.gbfs.drop_flagged()      # audit A1–A7 and keep the trustworthy stations
av = info.gbfs.join_status(status)    # availability frame
av.gbfs.occupancy()                   # bikes / (bikes + docks), NaN-safe

The same audit on a live network

Run against a live Vélib' Métropole feed (Paris), audit_static flags a small, explainable fraction of a real 1500-station network:

system_id                velib
gbfs_version             2.x
total_stations           1517
total_bikes_available    17063
feed_staleness_min       25.1

31 of 1517 stations flagged
Geospatial error            26
Structural over-capacity     5

The 26 geospatial outliers (A4) and 5 free-floating anchors (A3) are exactly the cases a study should inspect before trusting station coordinates or capacities. The exact figures vary with each live snapshot.

Citation and licence

If you use gbfs-toolkit in a publication, please cite it and the accompanying dataset paper. See Citing this work. Released under the MIT License. Affiliated with CESI LINEACT (EA 7527), Montpellier, France.