An overview of technical resources available to developers on http://thenexttrain.com
API Documentation
This site offers an API that can be queried by station or by pair of stations to return up to the next 5 departures at that station, or between those stations. There is also a API to request information about all stations at an agency, and one to get information about all available agencies.
General Information
Each url serves a dual purpose. It serves html results to browsers, and serves up JSON feeds to developers. To TEST the JSON feed, each url can have a parameter added to the end of the url to force the output type to JSON ?output=json . This must not be used for anything beyond testing. As part of the requirements to use this feed, http requests must set the HTTP_ACCEPT header to application/json (which will trigger the JSON output format), and must also set a valid HTTP_USER_AGENT which has the name of the application requesting data, and the url.
A valid request would be
GET /web HTTP/1.1
User-Agent: theNextTrain http://thenexttrain.com/
Accept: application/json
Accept-Encoding: gzip,deflate
Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.7
Keep-Alive: 300
Connection: keep-alive
For details on how to set the proper header values consult your programming language reference.
Agency List
- provides: A list of all available agencies, their name, a slug to use in future url requests, and a url to the agency website.
- url:
http://thenexttrain.com/web - test url:
http://thenexttrain.com/web?output=json
example output:
{
"agencies":[
{
"name":"Long Island Railroad",
"slug":"lirr",
"url":"http://mta.info/lirr/"
}
]
}
Station List
- provides: A list of all available stations at an agency, their name, location (if available), a slug to use in future url requests, and a url to the agency website (if available).
- url:
http://thenexttrain.com/at/{{agency_slug}}/ - test url:
http://thenexttrain.com/at/{{agency_slug}}/?output=json
Example Output:
{
"agency":{
"slug":"lirr",
"url":"http://mta.info/lirr/",
"name":"Long Island Railroad"
},
"stops":[
{
"url":"http://www.mta.nyc.ny.us/lirr/html/ttn/mineola.htm",
"slug":"mineola",
"name":"Mineola"
},
{
"url":"http://www.mta.nyc.ny.us/lirr/html/ttn/montauk.htm",
"slug":"montauk",
"name":"Montauk"
},
{
"url":"http://www.mta.nyc.ny.us/lirr/html/ttn/newhydep.htm",
"slug":"new-hyde-park",
"name":"New Hyde Park"
},
{
"url":"http://www.mta.nyc.ny.us/lirr/html/ttn/pennstat.htm",
"slug":"penn-station",
"name":"Penn Station"
}
]
}
Station Departures
provides: A list of up to the next 5 departures (if any) at the selected stop within the next 6 hours, some meta information about the results, the stop and the agency.
The results will begin listing departures with a -15 minute sliding window so users know if their is a train they just missed late, and to allow users to see listings for trains that might be late. IE: if you make a request at 3:00pm it will list the next 5 trains departing after 2:45pm. The start and end of the timeframe used for a given request are returned as part of the results.
No timezone information is needed as part of the requests, the results are calculated based on the current time at the station requested taking into account changes for daylight savings time.
url:
http://thenexttrain.com/at/{{agency_slug}}/{{station_slug}}/- test url:
http://thenexttrain.com/at/{{agency_slug}}/{{station_slug}}/?output=json
Example Output:
{
"request":"http://thenexttrain.com/at/lirr/new-hyde-park/",
"agency":{
"slug":"lirr",
"url":"http://mta.info/lirr/",
"name":"Long Island Railroad"
},
"stop":{
"name":"New Hyde Park",
"url","http://www.mta.nyc.ny.us/lirr/html/ttn/newhydep.htm",
"slug":"new-hyde-park"
},
"starting":"11:35pm",
"ending":"5:45am",
"departures":[
{
"time":"11:39pm",
"headsign":"OFF-PEAK Eastbound to Port Jefferson ",
"route":"Port Jefferson"
},
{
"time":"12:13am",
"headsign":"OFF-PEAK Eastbound to Port Jefferson ",
"route":"Port Jefferson"
},
{
"time":"12:58am",
"headsign":"OFF-PEAK Westbound to New York",
"route":"Port Jefferson"
},
{
"time":"3:38am",
"headsign":"OFF-PEAK Eastbound to Port Jefferson ",
"route":"Port Jefferson"
},
{
"time":"4:11am",
"headsign":"OFF-PEAK Westbound to New York",
"route":"Port Jefferson"
}
]
}
Trip Departures
provides: A list of up to the next 5 departures (if any) between the selected stations within the next 6 hours, some meta information about the results, the stop and the agency.
The results will begin listing departures with a -15 minute sliding window so users know if their is a train they just missed late, and to allow users to see listings for trains that might be late. IE: if you make a request at 3:00pm it will list the next 5 trains departing after 2:45pm. The start and end of the timeframe used for a given request are returned as part of the results.
No timezone information is needed as part of the requests, the results are calculated based on the current time at the station requested taking into account changes for daylight savings time.
url:
http://thenexttrain.com/at/{{agency_slug}}/{{station_slug}}/to/{{station_slug}}/- test url:
http://thenexttrain.com/at/{{agency_slug}}/{{station_slug}}/to/{{station_slug}}/?output=json
Example Output:
{
"request":"http://thenexttrain.com/at/lirr/penn-station/to/new-hyde-park/",
"agency":{
"slug":"lirr",
"url":"http://mta.info/lirr/",
"name":"Long Island Railroad"
},
"from":[
{
"name":"New Hyde Park",
"url","http://www.mta.nyc.ny.us/lirr/html/ttn/newhydep.htm",
"slug":"new-hyde-park"
}
],
"to":[
{
"name":"Penn Station",
"url","http://www.mta.nyc.ny.us/lirr/html/ttn/pennstat.htm",
"slug":"penn-station"
}
],
"starting":"11:40pm",
"ending":"6:00am",
"departures":[
{
"time":"12:58am",
"headsign":"OFF-PEAK Westbound to New York",
"route":"Port Jefferson"
},
{
"time":"4:11am",
"headsign":"OFF-PEAK Westbound to New York",
"route":"Port Jefferson"
},
{
"time":"4:59am",
"headsign":"OFF-PEAK Westbound to New York",
"route":"Port Jefferson"
}
]
}
Notice a problem? Have an idea? Drop us a Line