Interpreting Responses

As stated in the requests section, we support both JSON and XML from our RESTful endpoint as well as SOAP. The structure of the response does not change at all with the format.

Structure

Every response follows the same structure regardless of the format you use. There will always be one root response (rsp) element that contains the entire response. The response element will always contain a time field that has the time of the server when the request was processed. Each response will also contain a stat element indicating the status of the response. It contains a code field and a msg field to help you quickly interpret the response. For specific structural details, check the documentation on each method.

Each response element will also contain a rqst object with information about your request. It contains a method field with the API method that is being responded to as well as a params array containing all parameters that were supplied with the request. This should be useful for responding to requests that are made asynchronously.

Status Codes

The API uses status codes to indicate whether the request was successful or not. These codes are included in the stat element and are also sent as HTTP status codes for RESTful requests. Any status code 300 or above indicate a problem occurred. Below is a list of all the potential status codes and what they mean.

changeset_id

Many of the method calls return large datasets that change very infrequently (e.g. GetStops). To better accommodate caching we have included a changeset_id to be returned with any cacheable dataset as part of the response (rsp). It is determined by the date the data was updated and the parameters you send with the request.

Once a dataset has been returned with a changeset_id, submitting that changeset_id with the same parameters will generate a 202 "not modified" response from the server, indicating that the data has not changed. If the data has changed, you'll get a response like normal. If the changeset_id, parameters, or data on the server does not match the original request, you'll receieve a new dataset.

new_changeset

When used in conjunction with changeset_id, the new_changeset field indicates whether new data is being returned. If a changeset_id is not passed in, this field will always be true. If an invalid changeset_id is passed in (i.e. the data on the server has updated), this value will still be true. However, if a valid changeset_id is passed in with matching parameters, new_changeset will be false indicating that your cached data is still valid and the response is empty.