npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

gbfs-system

v1.1.2

Published

A Node.js package that enables real-time data retrieval from GBFS (General Bikeshare Feed Specification) using the auto-discovery URLs provided by MobilityData. It allows developers to easily access and utilize live bikeshare system information, station i

Downloads

63

Readme

Build Test license

1. Introduction

GBFS (General Bikeshare Feed Specification) is a standardized data feed for shared mobility system availability, such as bikes and scooters. It provides a unified format for sharing real-time information about the location, status, and availability of these systems.

2. Problem Statement

The gbfs-system library aims to simplify the interaction with GBFS-compliant systems, providing easy access to shared mobility data like station information, system status, and more. gbfs-system is a Node.js package to seamlessly retrieve real-time data from GBFS (General Bikeshare Feed Specification) using the auto-discovery URLs provided by MobilityData. Perfect for developers aiming to leverage live bikeshare system information, station statuses, and other essential data to innovate in their applications and services.

3. Installation

To install the library via npm, use the following command:

npm install gbfs-system

4. Usage

4.1 Systems Module

The Systems module helps in finding nearby bike systems based on a given city or location.

import { Systems } from "gbfs-system";
// Import the Systems module
// initialize the Systems class
const SYSTEMS = await Systems.initialize();

const system_data_by_location = SYSTEMS.findByLocation("dubai");
console.log(system_data_by_location);
/*
[{
  countryCode: 'AE',
  name: 'Careem BIKE',
  location: 'Dubai, AE',
  systemID: 'careem_bike',
  url: 'https://www.careem.com/en-ae/...',
  autoDiscoveryURL: 'https://dubai.public.../gbfs.json',
...
}]
*/

const system_data_by_country = SYSTEMS.findByCountryCode("BR");
console.log(system_data_by_country);
/*
[
  {
    countryCode: 'BR',
    name: 'Bike Itaú - Rio',
    location: 'Rio de Janeiro, BR',
    systemID: 'bike_rio',
    url: 'https://bikeitau.com...',
    autoDiscoveryURL: 'https://riodejaneiro.public...gbfs.json',
  ...
  },
  and 10 more...
]
*/

const system_data_by_name = SYSTEMS.findByName("bixi");
console.log(system_data_by_name);
/*
[
  {
  countryCode: 'CA',
  name: 'BIXI Montréal',
  location: 'Montréal, CA',
  systemID: 'Bixi_MTL',
  url: 'https://www.bixi...',
  autoDiscoveryURL: 'https://gbfs.velo...gbfs.json'
  }
]
*/

const system_data_by_id = SYSTEMS.findBySystemID("dott-paris");
console.log(system_data_by_id);
/*
{
  countryCode: 'FR',
  name: 'Dott Paris',
  location: 'Paris,FR',
  systemID: 'dott-paris',
  url: 'https://ridedott...',
  autoDiscoveryURL: 'https://gbfs.api...gbfs.json',
  validationReport: 'https://gbfs-validator...gbfs.json'
}
*/

4.2 Gbfs Module

The Gbfs module provides methods to interact with a GBFS-compliant system, such as fetching station information and system status.

import { Gbfs } from "gbfs-system";
// Import the Gbfs module
const autoDiscoveryURL = "https://gbfs.example.com/gbfs.json";

// create a new Gbfs instance with the auto-discovery url
const gbfs = await Gbfs.initialize(autoDiscoveryURL);

// Get all stations informations
const station_info_data = await gbfs.stationInfo();
console.log(station_info_data);
/* 
[
  {
    "station_id": "1",
    "name": "Métro Champ-de-Mars ( Viger / Sanguinet )",
    "short_name": "6001",
    "lat": 45.51025293,
    "lon": -73.5567766,
    "capacity": 35,
    ...
  },
  and 205 more...
] 
*/

// Get all stations status
const station_status_data = await gbfs.stationStatus();
console.log(station_status_data);
/* 
[
  {
    "station_id": "1",
    "num_bikes_available": 16,
    "num_ebikes_available": 3,
    "num_docks_available": 8,
    ...
  },
  and 205 more...
]
*/

// Get the system information
const system_info_data = await gbfs.systemInfo();
console.log(system_info_data);
/* 
{
  "system_id": "Bixi_MTL",
  "language": "en",
  "name": "Bixi_MTL",
  ...
} 
*/

// Get unified station_info and station_status data
const unified_stations_data = await gbfs.stationUnified();
console.log(unified_stations_data);
/* 
[
  {
    "station_id": "1",
    "num_bikes_available": 16,
    "num_ebikes_available": 3,
    "num_docks_available": 8,
    "name": "Métro Champ-de-Mars ( Viger / Sanguinet )",
    "short_name": "6001",
    "lat": 45.51025293,
    "lon": -73.5567766,
    "capacity": 35,
    ...
  },
  and 205 more...
]
*/

4.3 Get a Single Station Data

For stationInfo(), stationUnified() and stationStatus(), you can get a specific station data by providing its station_id.

gbfs.stationStatus("12").then((station) => console.log(station));

4.4 Feed Language Management

Some gbfs clients can provide their feed data in multiple languages depending on their public's needs. The example below from Velobixi in Montreal is the response data of the autodiscovery url (or gbfs.json). We can see the feeds are provided in english 'en' and in french 'fr'.

{
  "last_updated": 1234567890,
  "ttl": 10,
  "data": {
    "en": {
      "feeds": [
        {
        "name": "station_status",
        "url": "https://gbfs.velobixi.../en/station_status.json"
        },
        ...
      ]
    },
    "fr": {
      "feeds": [
        {
        "name": "station_status",
        "url": "https://gbfs.velobixi.../fr/station_status.json"
        },
        ...
      ]
    }
  }
}

You can fetch data in a different language with one of these 2 options:

// Change the feed language for the selected instance
gbfs.setPreferredFeedLanguage = "fr";

// Define language at creation
const gbfsInFrench = await Gbfs.initialize(autoDiscoveryURL, "fr");

To handle supported languages:

gbfs.getSupportedLanguages(); // ['en', 'fr']
gbfs.isLanguageSupported("fr"); // true

If no prefered feed language is defined, The first found feed language is used to retrieve data.

API Reference

Systems Module

| Method | Description | Parameters | Returns | | ------------------- | ----------------------------- | --------------------- | ---------------- | | initialize | Static factory method that creates a new Systems instance. | - | Systems | | findByLocation | Finds systems in a given city | location: string | Array<ISystem> | | findByCountryCode | Finds systems by country code | countryCode: string | Array<ISystem> | | findBySystemID | Finds a system by its ID | systemID: string | ISystem | | findByName | Finds systems by name | name: string | Array<ISystem> |

GBFS Module

| Method | Description | Parameters | Returns | | --------------- | ---------------------------------- | -------------------- | ------------------------------------ | | initialize | Static factory method that creates a new Gbfs instance with its url. | autoDiscvoeryURL:string and preferedFeedLanguage?: string | Gbfs | | stationInfo | Fetches station information | stationId?: string | Array<StationInfo> or StationInfo | | stationStatus | Fetches station status | stationId?: string | Array<StationStatus> or StationStatus | | systemInfo | Fetches general system information | - | SystemInfo | | stationUnified | Combines station_info and station_status data | stationId?: string | Array<StationUnified> or StationUnified | | getSupportedLanguages | Returns an array of all feed language codes | - | Array<string>| | isLanguageSupported | Returns true if the feed language code is supported | language:string | Boolean |

More methods will be added to support data retreival from other feeds.

Compatibility

The current package is designed for ESModules, so you can use the module you want with the import statement. Future versions aim to include compatibility with CommonJS. As for now, you can import the modules as mentioned above.

You might also consider the fact that some operators may have in place several security neasures on their API servers such as IP whitelisting, rate limits, etc that may sometimes impact the outcome of some requests and may throw errors like this :

Error: Failed to retrieve data from https://gbfs.example.com/system_information.json: AxiosError: Request failed with status code 403

Contributing

  • Contributions to the gbfs-system library are welcome. Please fork the project, create a new branche from main and name it like this : feature/your-awesome-feature. Once you done, push on the remote repository and create a pull-request.

  • For bugs and feature requests, please use the issues section on GitHub.

License

This project is licensed under the ISC License.

Contact

For any queries or contributions, please contact me here