Historical API

This API is modeled after the Operational API, and tries to behave in a similar manner where appropriate, only with additional functionality of exposing a time dimension.

This API returns raw/real-time data (i.e. directly from buses) in all cases, and corresponding inferred data when it is available. Certain arguments to this API depend on post-inference values, as described below. If any of those arguments are used, only data that has both raw/real-time and corresponding inferred records will be returned.

Call

(archive component)/api/history/record/last-known/list

One or more arguments may be passed in the URL to filter which buses are returned. Some combination of n-records, start, and end must be specified to limit/constrain the number of records returned. All are optional. However, start and end date parameters should always be specified for better performance. Inclusion of these parameters adds partition key to the query which enhances performance of the API significantly. It is also recommended to include record limit parameter to restrict the record size. The upper bound for record limit defaults to 3000 (this number is configurable by system administrators) if the record limit is not specified or is more than 3000 in the record limit parameter.

Options

Argument	Example Value	Description	Require Inference
depot-id	JG	2-letter depot code	Yes
inferred-route-id	MTA NYCT_S79	fully agency-qualified route id	Yes
inferred-phase	IN_PROGRESS,LAYOVER_BEFORE	OneBusAway phase or (comma-separated) phases	Yes
vehicle-id	330	vehicle to query on; no assumptions are made about vehicle agency id	No
vehicle-agency-id	MTA NYCT	Agency to which vehicle belongs	No
bbox	-74.16585,40.57280,-74.16376,40.574445	bounding box in lat/lon (min_lon, min_lat, max_lon, max_lat). any bus whose lat/lon or inferred_lat_lon fall w/in that bbox should be returned.	No
start-date	2012-07-07 03:00:00	start date and time of bounding query. When present, the end date need not be present, it will default to now(). Refers to the time the real-time update was first received by the sever.	No
end-date	2012-07-07 23:59:59	end date of bounding query. When present, the start date needs to be present OR n-records needs to be present.Refers to the time the real-time update was first received by the sever.	No
records	100	max number of records to return.	N/A

Response

The API defaults to returning a JSON response of the data:

  {  "records": [    {
      "vehicle-agency-id": "MTA NYCT",
      "time-reported": "2011-12-02T18:18:46.000Z",
      "time-received": "2011-12-02T18:18:49.000Z",
      "operator-id-designator": "511414",
      "route-id-designator": "051",
      "run-id-designator": "463",
      "dest-sign-code": 6518,
 "emergency-code": "1",
      "latitude": 40.618381,
      "longitude": -74.069248,
      "speed": 15.0,
      "direction-deg": 331.53,
      "agency-id": "MTA NYCT",
      "vehicle-id": 6158,
      "depot-id": "CAST",
      "service-date": "2011-12-02",
      "inferred-run-id": "MISC-463",
  "inferred-block-id":"MTA NYCT_MTA NYCT_20110904EA_CA_38700_MISC-463_41353",
      "inferred-trip-id": "MTA NYCT_20110904EA_077000_S51_0045_MISC_463",
      "inferred-route-id": "MTA NYCT_S51",
      "inferred-direction-id": "0",
      "inferred-dest-sign-code": "6518",
      "inferred-latitude": 40.618339,
      "inferred-longitude": -74.069261,
      "inferred-phase": "IN_PROGRESS",
      "inferred-status": "default",
      "inference-is-formal": false,
      "distance-along-block": 34194.6,
      "distance-along-trip": 9291.5,
      "next-scheduled-stop-id": "MTA NYCT_200142",
      "next-scheduled-stop-distance": 187.3,
      "schedule-deviation": 0
 } ]
 }