gbfs-api

gbfs-api is a lightweight implementation of the General Bikeshare Feed Specification (GBFS) built on top of CityBikes data. It provides a standardized HTTP API for accessing real-time bike share information.

The API supports GBFS versions 2.3 and 3.0.

Installation

git clone https://github.com/citybikes/gbfs-api
cd gbfs-api
pip install -e .

Usage

# init db
python -m citybikes.cmd.migrate

# seed with test data
python -m citybikes.cmd.seed

# start the API
python -m citybikes.cmd.srv --port 8000

# alternatively
uvicorn citybikes.gbfs.app:app --port 8000

Once the API is running, you can query endpoints such as:

http :8000/3/manifest.json
http :8000/3/bicing/gbfs.json
http :8000/2/velib/gbfs.json

Usage with CityBikes Hyper

For real-time data, install hyper and run a publisher and subscriber:

pip install git+https://github.com/citybikes/hyper
hyper publisher

python -m citybikes.cmd.subscriber

Now, citybikes.db contains real-time bike availability!

API Endpoints

• GET /<version>/<resource>
• GET /<version>/<network>/<resource>

For example:

• GET /3/manifest.json - Returns the GBFS v3 manifest document.
• GET /3/bicing/gbfs.json - Returns the GBFS v3 auto-discovery document for a bicing network.
• GET /2/velib/station_status.json - Returns the GBFS v2 station status document for a velib network.

See the full specification at https://docs.citybik.es/api/gbfs and https://github.com/MobilityData/gbfs

Configuration

• DB_URI - Path to the database (default: citybikes.db)
• TEST_DB_URI - Path to the test database (default: :memory:)

Development

To set up a local development environment:

# pull json schema fixtures
git submodule update --init --recursive

# install dev dependencies with uv
uv venv
source .venv/bin/activate
uv sync
uv pip install -e .

Running Tests

Run tests with:

pytest -vv

To run tests against a populated database, set up TEST_DB_URI:

export TEST_DB_URI='citybikes.db'
pytest -vv

This is useful for validating endpoints against the GBFS JSON schema.

License

gbfs-api is free, open-source software licensed under AGPLv3. See LICENSE for details.

Funding

This project is funded through the NGI0 Commons Fund, a fund established by NLnet with financial support from the European Commission's Next Generation Internet program. Learn more at the NLnet project page.