Skip to content

Examples

A set of worked, end-to-end scripts. The four core stages below are the path you would actually meet them in: audit an unknown feed, collect snapshots into a data lake, analyse the resulting history, then measure network equity. Further pages build on that base (robustness and equity, free-floating and ghost fleets, service reliability, transit and weather context, macro-scale comparison). Each has its own page with a step-by-step walkthrough, the command to run it, and the full source.

Core workflow

flowchart LR
    A["1. Audit a feed"] -->|trustworthy stations| B["2. Collect a snapshot"]
    B -->|repeat every few minutes| B
    B --> C["3. Analyse history"]
    A --> D["4. Equity and coverage"]

Auditing comes first, because every later step should run on the trustworthy subset of stations. Collection is repeated on a schedule to build a panel; analysis and the equity report then read from what was collected. The remaining how-to pages extend this core path.

Example Goal Extras
Audit a feed Inspect an unknown feed and keep the trustworthy stations [fetch]
Collect a snapshot One cron-driven collection run into a Parquet lake [fetch], [parquet]
Analyse history Coverage, daily typologies and turnover from a built-up lake [parquet], [cluster]
Equity and coverage Capacity concentration and spatial equity of a network [fetch], [geo]
Rigorous & comparative analysis Threshold robustness, bootstrap CIs, FDR hotspots, Theil/Palma, E2SFCA, rebalancing tension none (bundled data)
Free-floating & ghost fleets Reconcile docked + free-floating, ghost vehicles, spatial-entropy collapse none (synthetic)
Service reliability Stockout episodes, Kaplan–Meier outage survival, sampling vulnerability none (synthetic)
Contextualize with transit & weather Transit feeders, leak-free exogenous join, autocorrelation none (synthetic)
Macro-scale comparative audit Filter the world catalogue and audit N feeds in one call [fetch] (live)

The scenarios marked none use the bundled load_example() dataset and small synthetic frames, so they run with no network and are executed in CI.

Install what a script needs, for example:

pip install "gbfs-toolkit[fetch,parquet,cluster,geo]"

The runnable .py files live in the examples/ directory of the repository. For instant, network-free reproduction, a quickstart notebook runs the audit, occupancy and a descriptive profile on the bundled sample.

Finding a system id

Examples 02 and 03 resolve a system by its MobilityData catalogue id (velib, bike_share_toronto, and so on). Examples 01 and 04 take a gbfs.json URL directly. To find an id:

import gbfs_toolkit as gb

cat = gb.systems_catalog()
gb.filter_catalog(cat, country_code="FR")[["system_id", "name"]]

Feeds change without notice

GBFS feeds are operator-run. A URL that worked last month may move or break, and the exact fields a feed publishes vary by operator and GBFS version. The audit is designed to make those differences visible rather than to assume them away.