Skip to content
cascadiacollectionsPublic

About

Node.js client for Citi Bike NYC's public GBFS feeds (station information and live availability)

Topics

Resources

Contributing

Security policy

Stars

41 stars

Watchers

6 watching

Forks

Latest commit

 

History

117 Commits

Folders and files

Repository files navigation

Citibike

npm version

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.

Installation

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

Requirements

  • Node.js 22 or newer (active LTS lines). No runtime dependencies.

Data source

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.

Examples

Demos of the citibike module are located in: ./examples

API Documentation

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: ..." }

Testing

You can test citibike (tests use local GBFS fixtures and never hit the network):

  $ npm test

Contributors

License

MIT. Copyright (c) 2014-2016 Kevin T. Coughlin.

About

Node.js client for Citi Bike NYC's public GBFS feeds (station information and live availability)

Topics

Resources

Contributing

Security policy

Stars

41 stars

Watchers

6 watching

Forks

Releases

Packages

Used by

Contributors

Languages