The TransLoc PublicAPI 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.

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.

Terms of Use

Your use of the API is subject to Terms of Service. Please see the “Terms & Conditions” tab for more information.

Versions

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_version and api_current_version fields in all responses from the OpenAPI.

Data Formats

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.

Identifiers

All identifiers, such as agency_id, route_id, stop_id or vehicle_id are guaranteed to be globally unique. Some of these IDs may appear numeric, but all of them must be treated as strings.

Dates and Times

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.

Geo Areas

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:

• Rectangle form

geo_area=35.80176,-78.64347|35.78061,-78.68218

• Point and radius form

geo_area=35.80176,-78.64347|75.5

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.

Rate Limits

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.

Available Resources

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.

Designing Your Application

Typically, the basic flow of your application would look as follows:

• Request a list of agencies available.
• For each agency of interest, cache the stops, segments and routes.
• Periodically request the vehicle information and/or the arrival estimates, and indicate the position of the markers on the map.