Skip to main content

Python client for discovering and capturing GBFS bikeshare feeds.

Project description


Build Status Coverage Status

A Python client for discovering and capturing live bikeshare data feeds made publically available by hundreds of global bikeshare providers in accordance with the General Bikeshare Feed Specification (GBFS) standard.

This module is built with the intention of laying some of the groundwork for supporting more complex applications built around the consumption of live bikeshare data.

System coverage

As of writing, this Python client supports 256 bikeshare systems across 218 cities in 36 countries.

The list of bikeshare systems supported by this client is actively maintained by the GBFS community and can be found here:

The code example below demonstrates how to discover and filter these systems programatically.


Install from PyPi using pip, a package manager for Python.

 pip install gbfs-client


A sample implementation (Flask JSON endpoint) can be found here:

Interactive walk-through

Searching for bikeshare systems in WI and NY using the system discovery service:

>>> from import SystemDiscoveryService
>>> ds = SystemDiscoveryService()
>>> len(ds.system_ids)
>>> [x.get('System ID') for x in if 'WI' in x.get('Location')]
['bcycle_bublr', 'bcycle_madison']
>>> ds.get_system_by_id('bcycle_madison')
{'Country Code': 'US', 'Name': 'Madison B-cycle', 'Location': 'Madison, WI', 'System ID': 'bcycle_madison', 'URL': '', 'Auto-Discovery URL': ''}
>>> [x.get('System ID') for x in if 'citi bike' in x.get('Name').lower()]
['NYC', 'jump_nyc', 'lime_new_york', 'reddy_bikeshare', 'sobi_long_beach']
>>> ds.get_system_by_id('NYC')
{'Country Code': 'US', 'Name': 'Citi Bike', 'Location': 'NYC, NY', 'System ID': 'NYC', 'URL': '', 'Auto-Discovery URL': ''}

Instantiating a GBFS client for Citi Bike (NYC) and exploring its available feeds:

>>> client = ds.instantiate_client('NYC')
>>> client.feed_names
['system_alerts', 'system_information', 'station_information', 'station_status', 'system_regions']
>>> client.request_feed('system_alerts')
{'last_updated': datetime.datetime(2018, 12, 3, 1, 49, 55), 'ttl': 10, 'data': {'alerts': []}}

Instantiating a GBFS client directly (without the discovery service) using the auto-discovery URL for Citi Bike (found earlier):

>>> from gbfs.client import GBFSClient
>>> client = GBFSClient('', 'en')

Searching Citi Bike's station_information feed for two specific stations, one near 49th/8th ave and the other near Barclay/Church:

>>> stations = client.request_feed('station_information').get('data').get('stations')
>>> [(x.get('name'), x.get('station_id')) for x in stations if '49' in x.get('name')]
[('Broadway & W 49 St', '173'), ('W 49 St & 8 Ave', '450'), ('49 Ave & 21 St', '3606')]
>>> home = next(filter(lambda x: x.get('station_id') == '450', stations))
>>> home
{'station_id': '450', 'name': 'W 49 St & 8 Ave', 'lat': 40.76227205, 'lon': -73.98788205, 'capacity': 59}
>>> [(x.get('name'), x.get('station_id')) for x in stations if 'Barclay' in x.get('name')]
[('Barclay St & Church St', '417')]
>>> work = next(filter(lambda x: x.get('station_id') == '417', stations))
>>> work
{'station_id': '417', 'name': 'Barclay St & Church St', 'lat': 40.71291224, 'lon': -74.01020234, 'capacity': 23}

Building a small app to poll a station's live status and print a nice message:

>>> def live_status_for(station):
...     all_statuses = client.request_feed('station_status').get('data').get('stations')
...     return next(filter(lambda x: x.get('station_id') == station.get('station_id'), all_statuses))

>>> def print_status_message(station):
...     bikes_available = live_status_for(station).get('num_bikes_available')
...     print('{} is currently at {}% capacity with {} bikes available to rent.'.format(
...         station.get('name'), int(100*bikes_available/station.get('capacity')), bikes_available))

>>> print_status_message(home)
W 49 St & 8 Ave is currently at 16% capacity with 10 bikes available to rent.
>>> print_status_message(work)
Barclay St & Church St is currently at 91% capacity with 21 bikes available to rent.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

gbfs-client-0.1.8.tar.gz (34.6 kB view hashes)

Uploaded Source

Built Distribution

gbfs_client-0.1.8-py2.py3-none-any.whl (18.5 kB view hashes)

Uploaded Python 2 Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page