New real-time regional bus data is now available!

Colour Stripe
Mobile Colour Stripe

This section covers the things you need to know in order to integrate with our API endpoints.

Please note that technical knowledge is assumed:

  • Programming experience in a web environment
  • Familiarity with the following technical standards:
    • HTTP (Hypertext Transfer Protocol)
    • URLs (Uniform Resource Locators)
    • JSON (JavaScript Object Notation)

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.

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.

Back to top