This section covers the things you need to know in order to integrate with our API endpoints.Please note that the following technical knowledge is assumed:
Programming experience in a web environment
Familiarity with the following technical standards:
An endpoint is a URL that you send API requests to. Different types of requests will have different endpoints/URLs.
Server Details
The TfNSW API Gateway server name is api.transport.nsw.gov.au and runs an HTTPS server on port 443.
Each endpoint URL will begin with:
Key Type: Production
Base URL: https://api.transport.nsw.gov.au/v1/
The 'v1' component of the URL is the API version number. If a new version of the API is ever released that is no longer backwards-compatible with the current interface, this version number will be changed. This is to ensure that any application designed to work with a particular version of the API will not be impacted by future releases.
Technologies
The TfNSW API Gateway incorporates a number of standard web technologies. They were chosen to be lightweight, free and easy to use.
All API endpoints use HTTP as the transport mechanism
Some endpoints respond with messages encoded in JSON
Most endpoints are called by using a single HTTP GET request, some taking named parameters in the query component of the URL. The response, if it is a validation error, will be returned as JSON (JavaScript Object Notation) object. If it is a successful response, the type of the response will vary depending on the API. The HTTP content type of the response will let you know the type.
Authenticating
In order to use the TfNSW API Gateway you will need an API key. An API key is like a password that identifies your application when sending requests to our server. If you are developing multiple applications that will use the API, we request that you obtain a separate API key for each.
Getting an API key
To obtain an API key you must register for an account on the TfNSW API Gateway. Once you have registered and activated your account, you will need to add an application for a key. You can also view your API keys on the Applications page at any time.
Important: Because API keys are linked to you and your application, you should keep them private. Avoid exposing them in URLs or anywhere in your web page mark-up. If you would like to do AJAX-based searches, we recommend proxying the search requests through your own server.
If you would like to add another user to your application, please contact us with the username you want added and your application name.
Using your API key
API Key
When calling an endpoint, you specify your API key as an HTTP header called Authorization. For example, if your API key was ak123, your request URL will include a header like:
Authorization: apikey ak123
If you do not specify an API token, or the value is incorrect, the API call will fail with:
An HTTP status code of 401 (Unauthorized)
A JSON message similar to:
{
"ErrorDetails": {
"TransactionId": ""00000153065eb1f7-38f0e",
"ErrorDateTime": ""2016-03-19T04:35:02.676-04:00"",
"Message": ""The calling application is unauthenticated."",
"RequestedUrl": "/v1/gtfs/alerts/buses",
"RequestMethod": "GET"
}
}
Note: You can also receive HTTP 401 status codes if you go over your limits. See limits for details.
Limits
In order to provide a high quality of service to all users, there are limits applied to the usage of the API.
There are currently two types of limits:
Throttle limit
Quota limit
All API endpoints within an API share the same limits.
The default account plan is the "Bronze Plan", which has the following limits:
Quota: 60,000 per day
Rate Limit: 5 per second
Tip: If these limits are too restrictive for your application (or you go over your limit), please contact us about increasing your usage threshold.
Throttle Limit
The throttle limit restricts the number of times your application can access the API per second. When your go over your throttle limit, subsequent requests (within the same second) will fail with:
An HTTP status code of 403 (Forbidden)
An HTTP header called X-Error-Detail containing the message 'Account Over Rate Limit'
The following JSON message:
{
"code": 403,
"message": "Account over rate limit"
}
Quota Limit
The quota limit restricts the number of times your application can access the API in a single day. When your go over your quota limit, subsequent requests (within the same day) will fail with:
An HTTP status code of 403 (Forbidden)
An HTTP header called X-Error-Detail containing the message 'Account Over Quota Limit'
The following JSON message:
{
"code": 403,
"message": "Account over rate limit"
}
Viewing Your Limits
To view your limits, and your current API usage, visit the Applications (you need to be logged in otherwise the page will return a 404) page and click on the application you want to check.
You should be able to see your current quota usage, your quota limit (calls per day) and your throttle limit (calls per second).
HTTP Status Code
The HTTP status code is always returned by the server. If an endpoint returns an HTTP status code other than 200 (OK), an authentication or other server error has occurred. In this case, there may or may not be a JSON message returned.
See also: HTTP Status Codes for a list of what codes can be raised, and what they mean.