NYC Bus Performance API

api.busturnaround.nyc

Overview

The NYC Bus Performance API provides a quick and easy way to request a variety of MTA/NYCT Bus performance metrics based on multiple criteria. Bus performance has been inferred from collected MTA Bus Time positions data and comparison with MTA GTFS schedules data.

For the purposes of transit analysis, services are categorized as either high or low frequency:

Endpoints

Base URI: http://api.busturnaround.nyc/api/v1/

Endpoint

Data Provided

service

Number of scheduled buses compared with number of observed buses; scheduled frequency compared with observed frequency. Accepts a variety of filters, aggregations, and sorts (see section below).

ewt

Excess Wait Time. During high frequency scheduled service, the average wait time per passenger implied by the schedule compared with the average wait time inferred from actual bus movements. Accepts a variety of filters, aggregations, and sorts (see section below).

wtp

Wait Time Probability. The chance of waiting less than 5, 10, 15, 20, or 30 minutes when arriving at a bus stop at random during high frequency scheduled service. Accepts a variety of filters, aggregations, and sorts (see section below).

otp

On Time Performance. How often buses departed early, on time, and late during low frequency scheduled service. Accepts a variety of filters, aggregations, and sorts (see section below).

speed

Average bus speeds, revenue vehicle miles, and revenue vehicle hours. Accepts a variety of filters, aggregations, and sorts (see section below).

routes

Bus route names and associated GTFS data. Accepts zero or more route_ids (e.g., /routes returns information on all routes; routes?routes=S48 returns information on a single route; routes?routes=S48,S98 returns information on multiple routes).

stops

Bus stop codes, names, and GPS coordinates. Accepts zero or more stop_ids (e.g., stops returns information on all stops; stops?stops=999999 returns information on a single stop; stops?stops=999999,200884 returns information on multiple stops).

Filters, Aggregations, and Orderings

The performance metric endpoints (service, ewt, wtp, and otp) all accept a variety of filters, aggregations, and orderings, which are passed as parameters:

For example, to see Excess Wait Time metrics for the M4 broken down by month, you would send: ewt?routes=M4&groups=month

Parameter

Details

months

A comma-delimited list of months, expressed as the first day of the month in YYYY-MM-DD or YYYYMMDD format. For example, “months=2016-01-01,2016-02-01” will return results for all of January and February 2016. If no months are passed, results are returned for all available months (currently August 2014 through February 2016).

routes

A list of route_ids (e.g., “routes=S48”, “routes=M4,M5”). If no routes are passed, results are returned for all bus routes. Be sure to URL-encode the bus route (e.g., pass “M60%2B” for data on the M60 SBS; route_id=M60+).

stops

A list of stop_ids (e.g., “stops=999999”). If no stops are passed, results are returned for all stops.

weekend

Whether to include or exclude weekends and holidays. Passing “weekend=0” excludes weekends and holidays; passing “weekend=1” includes only weekends and holidays. If the weekend parameter is not passed, results for both weekday and weekend services are returned.

periods

A list of integers indicating the desired times of day:

  1. 7am–10am
  2. 10am–4pm
  3. 4pm–7pm
  4. 7pm–11pm
  5. 11pm–7am

For example, passing “periods=1,3” along with “weekend=0” would return results for rush hour only.

sbs

Whether to include or exclude Select Bus Service (SBS). Passing “sbs=0” excludes all SBS routes; passing “sbs=1” includes only SBS routes. If the sbs parameter is not passed, results for both SBS and non-SBS routes are returned. Since exact stop times are not advertised for SBS, it is suggested to exclude SBS from On Time Performance analysis.

groups

A list of fields to aggregate by. Any of: year, month, route_id, stop_id, weekend, period. For example, passing “groups=month,route_id” will return results broken down by both month and route.

order

A list of fields to sort by. Any of: year, month, route_id, stop_id, weekend, period. Additionally, you may also sort by any of the returned metrics, which depends on the endpoint you’re calling. See the section below for a list of metrics returned for each endpoint. To sort a field in descending order, prefix the field name with a hyphen; e.g., “order=-scheduled” would sort by number of scheduled bus departures in descending order.

limit

The maximum number of results to return. In conjunction with the “order” parameter, useful for “Top 10” lists.

Metrics

Endpoint

Returned Metrics

service

  • scheduled : the number of scheduled bus departures (times a bus is scheduled to pick up any waiting passengers)
  • observed : the number of bus departures or passes inferred from Bus Time
  • missing : the percentage of scheduled departures not observed
  • scheduled_freq : the average number of scheduled departures per hour
  • observed_freq : the average number of observed departures per hour

ewt

  • swt : during high frequency scheduled service, the average Scheduled Wait Time per passenger, in seconds
  • awt : during high frequency scheduled service, the average Actual Wait Time per passenger, in seconds
  • ewt : during high frequency scheduled service, the average Excess Wait Time per passenger, in seconds
  • scheduled : the number of bus departures scheduled during high frequency service
  • observed : the number of bus departures or passes inferred from Bus Time during high frequency scheduled service

wtp

  • wtp_5, wtp_10, wtp_15, wtp_20, wtp_30 : the percentage chance of waiting less than 5, 10, 15, 20, or 30 minutes when arriving at a bus stop at random during high frequency scheduled service
  • hours : the number of hours measured (during high frequency scheduled service)

otp

  • early : during low frequency scheduled service, the percentage of times a bus was observed departing or passing a stop more than a minute ahead of schedule
  • on_time : during low frequency scheduled service, the percentage of times a bus was observed departing or passing a stop on time
  • late : during low frequency scheduled service, the percentage of times a bus was observed departing or passing a stop more than five minutes behind schedule
  • observed : the number of bus departures or passes inferred from Bus Time during low frequency scheduled service

speed

  • distance : the cumulative distance traveled by buses between a stop and the next stop on the route, in miles
  • travel_time : the cumulative amount of time that elapsed between buses departing a stop and departing the next stop on the route, in hours
  • speed : the average speed of buses traveling between a stop and the next stop on the route, in miles per hour

Additional Returned Data

In addition to the performance metrics, queries also return additional data on aggregated fields, such as descriptions of bus routes and GPS coordinates of bus stops.

Sample Queries

Percentage of Missing Buses per Route, 2015:

service?years=2015&groups=route_id

Average Scheduled Frequency vs Observed Frequency per Weekday Period, M60 SBS:

service?routes=M60%2B&weekend=0&groups=period

System-wide Rush Hour EWT, February 2016:

ewt?months=2016-02-01&weekend=0&periods=1,3

M35 EWT per Stop, April–June 2015:

ewt?routes=M35&months=2015-04-01,2015-05-01,2015-06-01&groups=stop_id

Probability of Waiting Less Than 10 Minutes During Rush Hour per Route, October 2015:

wtp?months=2015-10-01&weekend=0&periods=1,3&groups=route_id

Top 10 Routes Most Early Night Buses, April–June 2015 (Excluding SBS):

otp?months=2015-04-01,2015-05-01,2015-06-01&periods=5&sbs=0&groups=route_id&order=-early&limit=10

Top 10 Slowest Routes, Weekday Daytime, 2015:

speed?years=2015&weekend=0&periods=1,2,3&groups=route_id&order=speed&limit=10