OneBusAway provides a RESTful (REpresentational State Transfer) API that allows you access to the same information that powers the OneBusAway website and mobile tools. You can use the api to write cool new apps of your own.
Check out the Release Notes for details about what’s changed with the API
The following parameter must be included in all API requests:
Example:
/some/api/call.xml?key=YOUR_KEY_HERE
The assigned application key is used to track usage statistics across applications. API keys can be managed in a number of ways.
Supported output formats include JSON and XML. The output format is determined by the request extension. For example:
/some/api/call.xml
will return XML results, while
/some/api/call.json
will return JSON. The JSON method all supports a callback parameter, which is useful for cross-site scripting access:
/some/api/call.json?callback=some_function_name
will return:
some_function_name({"key":value,...})
All responses are wrapped in a response element.
<response>
<version>2</version>
<code>200</code>
<text>OK</text>
<currentTime>1270614730908</currentTime>
<data>
<references/>
...
</data>
</response>
The response element carries the following fields:
The <references/> element contains a dictionary of objects referenced by the main result payload. For elements that are often repeated in the result payload, the elements are instead included in the <references/> section and the payload will refer to elements by and object id that can be used to lookup the object in the <references/> dictionary.
Right now, only a few types of objects will ever appear in the references section: agencies, routes, stops, trips, and situations.
<references>
<agencies>
<agency>...</agency>
</agencies>
<routes>
<route>...</route>
</routes>
<stops>
<stop>...</stop>
</stops>
<trips>
<trip>...</trip>
</trips>
<situations>
<situation>...</situation>
</situations>
</references>
They will always appear in that order, since stops and trips reference routes and routes reference agencies. If you are processing the result stream in order, you should always be able to assume that an referenced entity would already have been included in the references section.
Every API method supports an optional includeReferences=true|false parameter that determines if the <references/> section is included in a response. If you don’t need the contents of the <references/> section, perhaps because you’ve pre-cached all the elements, then setting includeReferences=false can be a good way to reduce the response size.
The current list of supported API methods.
(Trip planning is no longer supported, check out the OpenTripPlanner project instead)
See more discussion of Version 2 of the API and how element references have changed:
Many API methods return timestamps. For the most part, a OneBusAway timestamp is a measure of the number of milliseconds since midnight, January 1, 1970 UTC.
Many API methods also accept a “time” parameter that can be used to query the API at a specific point in time (eg. list all active service alerts on a particular date). The semantics of how the time parameter is used by the method is method-specific but the parameter is parsed in the same way. You can specify time in two possible forms:
In human-friendly mode, the time will be parsed relative to the timezone where the OBA server is operating.