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.
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.
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.
||The request was completed successfully.|
||A parameter was invalid.|
||The key provided is invalid.|
||The hourly request limit on the given key has been reached.|
||The requested method does not exist.|
||The server encountered an error.|
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.
When used in conjunction with
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.
If a problem occurs, the status code and a description of the problem will be provided in the payload as follows.