tfl.api

Transport For London NodeJS API Wrapper (tfl.api)

Simple NodeJS wrapper API for https://api.tfl.gov.uk/ using superagent and promises.

Installation

npm install tfl.api --save

Contributing

Contributions are welcome. Please submit a pull request. If you encounter any issues, please submit an Issue.

Usage

The Transport for London API requires the use of an app_id and app_key. You can register for one at TFL API Portal.

The package can then be used as follows:

var appId = '<YOUR_APP_ID>';
var appKey = '<YOUR_APP_KEY>';
var tfl = require('tfl.api')(appId, appKey);

• Accident Stats
• Bikepoint (TODO)
• Cycle Super Highway (TODO)
• Journey
• Line (TODO)
• Mode (TODO)
• Occupancy
• Place
• Road (TODO)
• Search
• StopPoint

Each type of API can also be required separately as outlined in the examples below. Also see tests for samples.

Below is an outline of methods available to query. This library uses superagent to make HTTP requests. Responses are returned as promises and response content can be accessed through r => response.body.

Accident Stats

Implements API endpoint as supported by TFL Accident Stats

var tfl = require('tfl.api')(appId, appKey);
// or var accidentstats = require('tfl.api/accidentstats')(appId, appKey)

// Get accident stats for the year 2015
tfl.accidentstats(2015).then(r => console.log(r.body))

Journey

Implements API endpoint as supported by TFL Journey

var tfl = require('tfl.api')(appId, appKey);
// or var journey = require('tfl.api/journey')(appId, appKey)

var origin = '1001067';   // City Thameslink
var destination = '1000123'   // Kentish Town

// Get a journey plan from City Thameslink to Kentish Town
tfl.journey(origin, destination).then(...)
tfl.journey(origin, destination, { via: '...', other: 'options'}).then(...)

// Get Meta data for journey given a type as per TFL API
tfl.journey.meta('modes').then(...)

Occupancy

Implements API endpoint as supported by TFL Place

var tfl = require('tfl.api')(appId, appKey);
// or var occupancy = require('tfl.api/occupancy')(appId, appKey);

// Get occupancy of all car parks
tfl.occupancy.carPark().then(...)

// Get occupancy of a car park by id
tfl.occupancy.carParkById().then(...)

Place

Implements API endpoint as supported by TFL Place

var tfl = require('tfl.api')(appId, appKey);
// or var place = require('tfl.api/place')(appId, appKey);

// Retrieve a place by ID. Second argument can pass additional query params
tfl.place.byId(123, { includeChildren: true }).then(...)

// Retrieve places by lat/lng/radius
tfl.place({ lat: 123, lon: 987, radius: 100}).then(...)

// Retrieve places within a bounding box
tfl.place({ swLat: 123, swLon: 987, neLat: 100, neLon= 999 }).then(...)

// Get places of the given type at the given latitude and longitude
tfl.byTypeAtLatLon('placeTypes', 123, 999).then(...)

// Get metadata
tfl.meta('placeTypes').then(...)

Search

Implements method supported by TFL Search

var tfl = require('tfl.api')(appId, appKey);
// or var search = require('tfl.api/search')(appId, appKey);

// Search TFL with a query
tfl.search({ query: 'Thameslink' }).then(r => console.log(r.body))

// Search TFL with a query and pagination options
tfl.search({ query: 'Thameslink', pageSize: 5, pageFrom: 2 }).then(r => console.log(r.body));

// Get metadata for search methods
tfl.search.meta().then(r => console.log(r.body))

// Get bus schedules
tfl.search.busSchedules('<query>').then(r => console.log(r.body))

StopPoint

Implements API endpoint as supported by TFL StopPoint

var tfl = require('tfl.api')(appId, appKey);
// or var stoppoint = require('tfl.api/stoppoint')(appId, appKey);

// Gets a list of StopPoints corresponding to the given list of stop ids. 
tfl.stoppoint.byId('940GZZLUASL').then(...)

// Retrieve stoppoint by lat/lng/stopTypes
tfl.stoppoint({ lat: 51.467074, lon: -0.188808, stopTypes: 'NaptanPublicBusCoachTram'}).then(...)

// Retrieve stoppoint within a bounding box
tfl.stoppoint({ swLat: 123, swLon: 987, neLat: 100, neLon: 999, stopTypes: 'NaptanPublicBusCoachTram' }).then(...)

// Gets the list of arrival predictions for the given stop point id 
tfl.stoppoint.byIdArrivals('490014185E').then(...)

// Gets Stopoints that are reachable from a station/line combination. Third argument can pass additional query params
tfl.stoppoint.byCanReachOnLine('940GZZLUASL', 'victoria', { serviceTypes: 'regular,night'}).then(...)

// Gets the canonical direction, "inbound" or "outbound", for a given pair of stop point Ids in the direction from -> to. Third argument can pass additional query params
tfl.stoppoint.byDirectionTo('940GZZLUASL', '865GZZLUASL', { lineId: 'victoria'}).then(...)

// Gets all disruptions for the specified StopPointId, plus disruptions for any child Naptan records it may have. Second argument can pass additional query params
tfl.stoppoint.byIdDisruption('940GZZLUASL', { getFamily: false, includeRouteBlockedStops: false}).then(...)

// Gets all disruptions for the specified StopPointId, plus disruptions for any child Naptan records it may have. Forth argument can pass additional query params
tfl.stoppoint.byIdDisruptionStartEnd('940GZZLUASL','2016-08-12', '2016-08-14', { getFamily: false, includeRouteBlockedStops: false}).then(...)

// Gets metadata for methods that act upon the Stops controller. If metadataType is "categories", gets a list of all of the available stops property categories and keys, grouped by category name. If metadataType is "stoptypes", gets a list of the available types of stops. If metadataType is "modes", gets a list of the valid modes to filter stops by.
tfl.stoppoint.meta('stoptypes').then(...)

// Gets a list of StopPoints filtered by the modes available at that StopPoint. Second argument can pass additional query params
tfl.stoppoint.mode('bus', {page: 2}).then(...)

// Gets a distinct list of disrupted stop points for the given modes. Second argument can pass additional query params
tfl.stoppoint.modeDisruption('bus', {includeRouteBlockedStops: true}).then(...)

// Gets a distinct list of disrupted stop points for the given modes with a date range. Forth argument can pass additional query params
tfl.stoppoint.modeDisruptionStartEnd('bus', '2016-08-12', '2016-08-14', {includeRouteBlockedStops: false}).then(...)

// Returns the route sections for all the lines that service the given stop point ids. Second argument can pass additional query params
tfl.stoppoint.route('940GZZLUASL', {serviceTypes: 'night'}).then(...)

// Search StopPoints by their common name, or their 5-digit Countdown Bus Stop Code. Second argument can pass additional query params
tfl.stoppoint.search('Townmead Road', { modes: 'bus', faresOnly: false, maxResults: 50, lines: 2, includeHubs: true}).then(...)

// Gets the service types for a given stoppoint. Second argument can pass additional query params
tfl.stoppoint.servicetypes('940GZZLUASL', { lineids: '123', modes: 'bus'}).then(...)

// Gets a StopPoint for a given sms code. Second argument can pass additional query params
tfl.stoppoint.sms('73241', { output: 'web'}).then(...)

// Gets all stop points of a given type.
tfl.stoppoint.type('NaptanCoachBay,NaptanMarkedPoint').then(...)