The TransLoc Public API is a RESTful API which allows you to incorporate real-time vehicle tracking information into your web or mobile applications. It exposes several resources that allow you to access real-time information about transit systems tracked by TransLoc Inc. Following the REST principles, all the resources available through this API are located at specific URLs. You should use GET requests to access the resources behind the URLs. In all cases, if your request was successfully processed the HTTP status code will be returned as 200 OK. If an error occurs, an appropriate 400 or 500 level error will be returned, with the body of the response containing a plain text user-friendly error message.
Your use of the API is subject to Terms of Service. Please see the "Terms & Conditions" tab for more information.
Since deprecated versions of the OpenAPI are eventually retired, it is important to keep your application up-to-date with the latest version of the API. You can monitor for new versions of the API on the OpenAPI's Twitter Account or by looking at the values of
api_current_version fields in all responses from the OpenAPI.
The resources can be returned in JSON format. Also, you can use JSONP as a format with a
callback GET parameter. In the future other formats may be supported.
Note that if a 400 or 500 level error is returned, the
Content-Type header will be
text/plain since only a plain text message is returned.
All identifiers, such as
vehicle_id are guaranteed to be globally unique. Some of these IDs may appear numeric, but all of them must be treated as strings.
All dates and times are transmitted in the ISO 8601 date/time format. For example
2011-03-03T20:42:22+00:00 would be a UTC date/time string while
2011-01-10T17:55:33-05:00 is a local date/time.
Several of the API resources allow you to limit the results further via a geographical area filter. You are encouraged to use this feature to improve performance of your application. The
geo_area parameter can take on two distinct forms. The first is a rectangle, identified by two sets of geographical coordinates. The second is a point and radius representation. Examples:
Note that in the second form, the second parameter is a decimal number which represents the radius of the circle in meters, within which to return the results.
Most of the TransLoc Public API's resources are rate-limited in some fashion. Currently, this limit is enforced on per-IP address basis. Therefore, if you expect a large number of clients to your application to come from behind a NAT'ed network, you should cache API resources.
If the rate limit is reached for your IP address, you will receive a 429 Too Many Requests response status code, and the body of the message will contain a user-friendly error message.
Data available through the TransLoc Public API is divided into several resources. Each resource can be accessed via a URL and filtering options may be required to be passed in via the URLs query string. Each resource contains a "wrapper" which includes some API meta information. The fields in this section include:
api_version- the version of the API you are using
api_current_version- the version of the most current API, if you are not already using it
rate_limit- the number of seconds you should wait before requesting this resource again
generated_on- a date-time of when this resource was generated
expires_in- number of seconds from generated_on when this resource expires
For a list of all resources, please see the "Documentation" tab.
Typically, the basic flow of your application would look as follows: