MTBA API Client
mbta-client
is a promise-based Node.js client library for the MTBA API v3, with a few helper functions to parse response data.
Installation:
npm i mbta-client
Basic Usage
Fetch functions
import MBTA from 'mbta-client';
const mbta = new MBTA(YOUR_API_KEY);
const predictions = await mbta.fetchPredictions({ stop: 42 });
const stops = await mbta.fetchStops({ id: [70080, 'Back Bay'] });
const subwayRoutes = await mbta.fetchRoutes({ type: 'subway' });
const north = await mbta.fetchPredictions({ route: 'Red', direction_id: 1 });
const local = await mbta.fetchStops({ latitude: 42.373, longitude: -71.119 });
const sorted = await mbta.fetchPredictions({
stop: 42,
sort: 'arrival_time',
descending: true,
});
const alerts = await mbta.fetchAlerts({
sort: 'cause',
activity: 'BOARD',
datetime: 'NOW',
severity: [2, 3],
});
Helper functions:
Arrivals/Departures
Note: arrival and departure helpers have the same API/options.
const arr = mbta.selectArrivals(response);
const dep = mbta.selectDepartures(response, { convertTo: 'minutes' });
Fetch Helpers
const allRouteInfo = await mbta.fetchAllRoutes();
console.log(allRouteInfo);
const redLineStops = await mbta.fetchStopsByRoute('Red');
console.log(redLineStops);
const harvardStops = await mbta.fetchStopsByName('Harvard', { exact: true });
console.log(harvardStops);
Helper functions fetch the first, next, previous and last pages.
const results = await mbta.fetchPredictions({ stop: 42, limit: 2 });
const secondPageResults = await mbta.fetchNextPage(results);
const thirdPageResults = await mbta.fetchNextPage(secondPageResults);
const firstPageResults = await mbta.fetchFirstPage(results);
const lastPageResults = await mbta.fetchLastPage(results);
API
Fetch functions
These map to the endpoints listed in the MBTA docs. They return a promise that resolves to an MBTA response object. options
for each function maps to the filters listed on that page. options
that accept multiple values can be provided as an array or comma separated string.
mbta.fetchStops(options);
mbta.fetchTrips(options);
mbta.fetchRoutes(options);
mbta.fetchShapes(options);
mbta.fetchVehicles(options);
mbta.fetchServices(options);
mbta.fetchSchedules(options);
mbta.fetchFacilities(options);
mbta.fetchPredictions(options);
mbta.fetchLiveFacilities(options);
mbta.fetchAlerts(options);
The MBTA docs say: "Displaying alerts is one of the trickiest features to get correct." See their best practices and the alerts API docs for more information.
Helper functions
mbta.selectArrivals(response: MBTAResponse, options?: TimeOptions);
mbta.selectDepartures(response: MBTAResponse, options?: TimeOptions);
type TimeOptions = { convertTo?: 'ms' | 'seconds' | 'minutes' | 'hours' };
Note: arrival_time
could be null if it's the first stop on a route. If departure_time
is not null, the MBTA recommends using that instead. Departure could be null if it's the final stop on a route. See best practices for more info.
mbta.fetchAllRoutes(filters?: TypeOptions): Promise<BasicRouteResponse>;
mbta.fetchStopsByRoute(routeID: string|number): Promise<StopsByRouteResponse>;
mbta.fetchStopsByName(name: string, opts: NameOptions): Promise<MBTAResponse>;
mbta.selectIncluded(response: MBTAResponse, options?: TypeOptions);
type BasicRouteResponse = {
id: string,
long_name: string,
direction_names: string[],
short_name?: string
};
type StopsByRouteResponse = { name: string, id: string };
type TypeOptions = { type?: include_value | include_value[] };
type NameOptions = { exact: boolean };
See the MBTA API docs for include_value
options for each endpoint
(These return a promise that resolves to an MBTA response object)
Note: Input must include links
property.
mbta.fetchFirstPage(response: MBTAResponse);
mbta.fetchLastPage(response: MBTAResponse);
mbta.fetchNextPage(response: MBTAResponse);
mbta.fetchPrevPage(response: MBTAResponse);
MBTA API Documentation: https://api-v3.mbta.com/docs/swagger/index.html
MBTA API Best Practices: https://www.mbta.com/developers/v3-api/best-practices
Note: This library is not affiliated with the MBTA or MassDOT.
License
MIT