TLDR;

NSW Open Data Trip Planner API is a convenient API which provides loads of data related to New South Wales. It can be used to plan journeys from one place to another. (Ex : How to get from Central Station to Burwood city center, which trains buses/trains/ferried should I take to accomplish that, and when will those vehicles arrive)

NSW Open Data Hub (Link : https://opendata.transport.nsw.gov.au/) is a portal to gain access to New South Wales related data such as,

• Bus, Ferry, Train timetables
• Opal card related statistics and data
• Cycle way infrastructure related data
• Parking spaces
• Fuel prices across NSW

Pretty cool, ain’t it? These data sets come in various formats such as API’s, Zip files, and CSV files. In this tutorial we’ll learn how to get a list of transport methods and time tables available from one place to another as in Google Maps or TripView.

 

 

 

 

 

 

 

 

 

We’d be accessing the Trip Planner API’s (URL : https://opendata.transport.nsw.gov.au/node/601/exploreapi) of the Open Data Hub to obtain the information of the transport methods (buses/trains/ferries) that are available to travel from one place to another (With the estimated time it takes and when and to where the buses/trains/ferries arrive).

In order to do this we’d first need to create an application in the Open Data Hub. Visit https://opendata.transport.nsw.gov.au/node/add/application and add a name and a description and the set the app as enabled. Then click on the Add Items button in the API Management section.

From there select the Trip Planner APIs. This will enable us to access the necessary API’s to obtain data from the hub. Click on Save button to create the application. Now begins the fun part!.

Visit https://opendata.transport.nsw.gov.au/node/601/exploreapi to open the API Explorer, which allows you to play around with the functionality provided by the Trip Planner API. We are particularly interested in the /trip API. /trip allows us to find a list of possible journeys from a given start point to an end point on a particular date and time. In order to do that, we first need to find out the ID’s of the start position and the destination position.

The trip planner API assigns a unique identifier (a number) to each place so that it place can be identified. One easy way to find the ID of a place is to use the /stop_finder API which is available in the same API Explorer page.  But before using the API, we first need to select the authentication type for the requests. This is visible on top of the API Explorer page.

Select the application you created from the list (And no, that’s not my API key, so don’t waste your time!)

In the /stop_finder tab, keep all the values to default and change only the following values.

• type_sf = any
• name_sf = The name of the place you want to search for. Ex : “Wynyard Station”

Then click on the Try it out! button to check the response the API gives. The response will be similar to below.

The response provides a list matching locations to your search. Select the ID matching to your search. Do the same for both the starting location and destination location to find the id’s of them.

Now we can focus on the /trip API. /trip API expects the following parameters to be changed.

• depArrMacro = Whether you are setting the departure time or the arrival time. Ex : If you set the value as “dep”, all the journeys departing from the starting point after the given time will be considered.
• itdDate = The date on which the trips should be planned. The format is YYYYMMDD. For instance, 20170914 refers to 14 September 2017.
• itdTime = The time for which the trip needs to be planned. The format is HHMM in 24-hour. For an example, 2130 is 9.30PM.
• name_origin : The ID, which we found earlier, for the starting position of the journey.
• name_destination : The ID of the destination, which we found earlier.

Click on the Try it out! button to see the results. In order to understand the response, let’s get familiar with some terms.

• Journey = A route which was calculated by the API. For an example, to get form point A to D, there could be a path such as A -> B -> C -> D. There could also be a path such as A -> P -> Q -> R -> D. Thus there are two possible journey’s that can be taken to get from A to D.
• Leg = A leg is a sub part of a Journey. For an example consider the above example of getting to D from A via B and C. Here let’s assume to the following to get from A to D.
  • A -> B : Walk 500 m
  • B -> C : Take the bus with route number M41
  • C -> D : Take the train on platform 4 from C station

Details such as this is stored in a leg. The transportation section of a leg describes the transport methodology (Ex : vehicle class, route number, route name).

That’s it!. Now you know how to plan trips using the Open Data Hub Trip Planner API. Change the parameters and play with it!