A node.js client for Citi Bike's public GBFS data feeds.
A PHP port also exists, but it is archived and no longer maintained.
Install using the node.js package manager npm:
$ npm install citibike
Or...
Install via git clone:
$ git clone https://github.com/cascadiacollections/citibike.git
$ cd citibike
$ npm install
- Node.js 22 or newer (active LTS lines). No runtime dependencies.
Citi Bike retired its original appservices.citibikenyc.com REST API, which
versions 2.x of this library used. Since 3.0.0 the library reads Citi Bike's
public GBFS feeds (https://gbfs.citibikenyc.com/gbfs/gbfs.json),
specifically station_information and station_status, and maps them onto
the same { ok, meta, results, ... } envelope used before. The feeds are
run by Lyft: gbfs.json lists the same data under https://gbfs.lyft.com/gbfs/1.1/bkn/,
which you can pass as restBase (with /en appended) if you prefer that host.
| Method | 3.x behavior |
|---|---|
getStations() |
station_information + station_status, joined by station id |
getBranches() |
Discontinued. Always calls back with ok: false, no request is made |
getHelmets() |
Discontinued. Always calls back with ok: false, no request is made |
get() |
Generic GET + JSON parse for any URL (or path under restBase) |
See CHANGELOG.md for the full list of breaking changes.
Demos of the citibike module are located in: ./examples
Every callback receives a single object. When something goes wrong (network
error, timeout, non-2xx status, invalid JSON, or a discontinued method) the
object is { ok: false, meta: [], results: [], error: "<message>" }, so always
check data.ok first.
- Client - new Citibike( options )
var Citibike = require('citibike');
var citibike = new Citibike({
// all optional; these are the defaults
restBase: 'https://gbfs.citibikenyc.com/gbfs/en',
stationInformationURL: '/station_information.json',
stationStatusURL: '/station_status.json',
timeout: 10000, // ms
headers: { 'User-Agent': 'my-app/1.0' } // merged with the defaults
});- Stations - .getStations( params, callback )
citibike.getStations(null, function(data) {
if (!data.ok) return console.error(data.error);
console.log(data.results);
});Pass { updateOnly: true } to fetch only station_status (live availability,
no names or coordinates), like the old API's updateOnly flag.
- Sample JSON Response
{
"ok": true,
"meta": [],
"results": [
{
"id": "66db237e-0aca-11e7-82f6-3863bb44ef7c",
"status": "Active",
"availableBikes": 12,
"availableEbikes": 3,
"availableDocks": 22,
"lastReported": 1761955201,
"label": "W 52 St & 11 Ave",
"shortName": "6926.01",
"latitude": 40.76727216,
"longitude": -73.99392888,
"capacity": 39,
"stationAddress": ""
}
],
"activeStations": 1,
"totalStations": 1,
"lastUpdate": 1761955230
}status is "Active" when GBFS reports the station as installed and renting,
otherwise "Not In Service". lastUpdate is the station_status feed's
last_updated timestamp. Stations present in station_status but not (yet)
in station_information are left out of the full response.
- Branches - .getBranches( params, callback ) and Helmets - .getHelmets( params, callback )
Citi Bike no longer publishes branch or helmet-retailer locations, and GBFS has no equivalent. Both methods are kept so existing code does not crash, but they make no request and always call back (asynchronously) with:
{ "ok": false, "meta": [], "results": [], "error": "getHelmets() is not available: ..." }You can test citibike (tests use local GBFS fixtures and never hit the network):
$ npm test
MIT. Copyright (c) 2014-2016 Kevin T. Coughlin.