bikeshare-json-api: A Python repository from jakehadar

bikeshare-json-api

A JSON api for polling live Bikeshare feeds, demonstrating a simple bikeshare-client-python use-case.

The API spec is annotated in app.py

Installation

Clone this repo and install using setuptools.

 $ cd path/to/repos/bikeshare-json-api
 $ python setup.py develop

Usage

Once bikeshare-json-api is installed, start the flask app by running flask run from from command line.

 $ flask run

Open a browser or curl to http://127.0.0.1:5000/app/api/v1.0/systems (sub in your own local host & port) and start exploring!

Note: If Flask returns a 404 "Not Found" response, check that your request URL has a valid endpoint path, like /app/api/v1.0/systems (See Flask Routes table below). For example, GET http://127.0.0.1:5000/ would return a 404 because / is not a route in app.py.

Flask Routes

This table can be generated by running $ flask routes.

Resource name	Methods	Endpoint path
system_detail	GET	/app/api/v1.0/system/<string:system_id>
system_feed_detail	GET	/app/api/v1.0/system/<string:system_id>/feed/<feed_name>
system_feeds	GET	/app/api/v1.0/system/<string:system_id>/feeds
system_station_detail	GET	/app/api/v1.0/system/<string:system_id>/station/<string:station_id>
system_station_information	GET	/app/api/v1.0/system/<string:system_id>/station/<string:station_id>/status
system_station_status	GET	/app/api/v1.0/system/<string:system_id>/station/<string:station_id>/information
system_stations	GET	/app/api/v1.0/system/<string:system_id>/stations
systems	GET	/app/api/v1.0/systems

REST examples

Query all systems:

GET /systems

JSON Response (list of dictionaries, shortened for example):

[
    {"Auto-Discovery URL":"https://gbfs.nextbike.net/maps/gbfs/v1/nextbike_bn/gbfs.json","Country Code":"DE","Location":"Berlin, DE","Name":"Deezer nextbike","System ID":"nextbike_bn","URL":"https://www.deezernextbike.de/xx/berlin/"},
    {"Auto-Discovery URL":"https://gbfs.citibikenyc.com/gbfs/gbfs.json","Country Code":"US","Location":"NYC, NY","Name":"Citi Bike","System ID":"NYC","URL":"https://www.citibikenyc.com"}, 
    {"Auto-Discovery URL":"https://sea.jumpbikes.com/opendata/gbfs.json","Country Code":"US","Location":"Seattle, WA","Name":"JUMP Seattle","System ID":"jump_seattle","URL":"https://jump.com"}
]

Select CitiBike ("System ID": "NYC"):

GET /system/NYC

JSON Response (dictionary):

{
    "Auto-Discovery URL": "https://gbfs.citibikenyc.com/gbfs/gbfs.json",
    "Country Code": "US",
    "Location": "NYC, NY",
    "Name": "Citi Bike",
    "System ID": "NYC",
    "URL": "https://www.citibikenyc.com"
}

List of feeds provided by CitiBike:

GET /system/NYC/feeds

JSON Response (list of strings):

[
    "station_information",
    "system_regions",
    "system_alerts",
    "station_status",
    "system_information"
]

CitiBike system alerts (feed):

GET /system/NYC/feed/system_alerts

JSON Response (data structures vary by system and feed):

{
    "data": {
        "alerts": []
    },
    "last_updated": "Fri, 20 Sep 2019 15:14:39 GMT",
    "ttl": 10
}

Query all CitiBike stations:

GET /system/NYC/stations

JSON Response (list of dictionaries, shortened for example):

[
    {"capacity":60,"eightd_has_key_dispenser":false,"electric_bike_surcharge_waiver":false,"external_id":"66db3606-0aca-11e7-82f6-3863bb44ef7c","has_kiosk":true,"lat":40.74334935,"lon":-74.00681753,"name":"W 16 St & The High Line","region_id":71,"rental_methods":["KEY","CREDITCARD"],"rental_url":"http://app.citibikenyc.com/S6Lr/IBV092JufD?station_id=212","short_name":"6233.05","station_id":"212"},
    {"capacity":23,"eightd_has_key_dispenser":false,"electric_bike_surcharge_waiver":false,"external_id":"66db3687-0aca-11e7-82f6-3863bb44ef7c","has_kiosk":true,"lat":40.70037867,"lon":-73.99548059,"name":"Columbia Heights & Cranberry St","region_id":71,"rental_methods":["KEY","CREDITCARD"],"rental_url":"http://app.citibikenyc.com/S6Lr/IBV092JufD?station_id=216","short_name":"4829.01","station_id":"216"},
    {"capacity":39,"eightd_has_key_dispenser":true,"electric_bike_surcharge_waiver":false,"external_id":"66db3708-0aca-11e7-82f6-3863bb44ef7c","has_kiosk":true,"lat":40.70277159,"lon":-73.99383605,"name":"Old Fulton St","region_id":71,"rental_methods":["KEY","CREDITCARD"],"rental_url":"http://app.citibikenyc.com/S6Lr/IBV092JufD?station_id=217","short_name":"4903.08","station_id":"217"}
]

Live status of an arbitrary CitiBike station:

GET /system/NYC/station/212

JSON Responsee (dictionary):

{
    "capacity":60,
    "eightd_has_available_keys":false,
    "eightd_has_key_dispenser":false,
    "electric_bike_surcharge_waiver":false,
    "external_id":"66db3606-0aca-11e7-82f6-3863bb44ef7c",
    "has_kiosk":true,
    "is_installed":1,
    "is_renting":1,
    "is_returning":1,
    "last_reported":1568992566,
    "last_updated":"Fri, 20 Sep 2019 15:16:59 GMT",
    "lat":40.74334935,
    "lon":-74.00681753,
    "name":"W 16 St & The High Line",
    "num_bikes_available":52,
    "num_bikes_disabled":0,
    "num_docks_available":8,
    "num_docks_disabled":0,
    "num_ebikes_available":0,
    "region_id":71,
    "rental_methods":["KEY","CREDITCARD"],
    "rental_url":"http://app.citibikenyc.com/S6Lr/IBV092JufD?station_id=212",
    "short_name":"6233.05",
    "station_id":"212",
    "ttl":10
}

Uninstallation

Uninstall using pip to remove bikeshare-json-api (and its dependencies) from your environment.

 $ pip uninstall bikeshare-json-api

jakehadar/bikeshare-json-api