The OneBusAway RESTful API

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.

Release Notes

Check out the Release Notes for details about what’s changed with the API

API Keys

The following parameter must be included in all API requests:

  • key - your assigned application key

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.

Output Format

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,...})

Response Element

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:

  • version - response version information
  • code - a machine-readable response code with the following semantics:
    • 200 - Success
    • 400 - The request could not be understood due to an invalid request parameter or some other error
    • 401 - The application key is either missing or invalid
    • 404 - The specified resource was not found
    • 500 - A service exception or error occurred while processing the request
  • text - a human-readable version of the response code
  • currentTime - current system time on the api server as milliseconds since the unix epoch
  • data - the response payload
    • references see the discussion of references below

References

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.

Methods

The current list of supported API methods. Methods that are subject to changed are marked BETA. Methods that have a ~~strikethrough~~ are deprecated and no longer supported.

Common Elements

See more discussion of Version 2 of the API and how element references have changed:

Timestamps

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:

  • Millisecond since the epoch: time=1365259214945
  • “Human-friendly”: time=yyyy-MM-dd_HH-mm-ss

In human-friendly mode, the time will be parsed relative to the timezone where the OBA server is operating.