Trip Planner API Manual Opendataproduction V3.1
User Manual:
Open the PDF directly: View PDF 
.
Page Count: 37
| Download | |
| Open PDF In Browser | View PDF |
Trip Planner APIs: Manual
Open Data Production
Technical Documentation
Jun 2018 | Version: 3.1
Trip Planner APIs: Technical Documentation
1
Table of Contents
1.
Transport for NSW API.............................................................................................................................. 4
1.1.
Introduction ........................................................................................................................................... 4
A Note about Usage Examples ................................................................................................................ 4
A Note about Caching ................................................................................................................................. 4
A Note about Response Data ................................................................................................................... 5
JSON .................................................................................................................................................................. 5
Manually Performing Requests and Handling Responses ........................................................... 6
Using swagger-codegen to Build a Client Library ........................................................................... 7
1.2.
Stop Finder API..................................................................................................................................... 9
Example: Searching for a Stop ............................................................................................................. 10
Location Types........................................................................................................................................... 11
Finding a Stop by ID................................................................................................................................. 12
Extracting Address Parts ....................................................................................................................... 12
Coordinates ................................................................................................................................................. 13
1.3.
Trip Planner API ............................................................................................................................... 14
Data Returned in Trip Planner API .................................................................................................... 14
Example: Performing a Trip Planner Request............................................................................... 15
Example: Real-Time Data ...................................................................................................................... 18
Example: Arrive By .................................................................................................................................. 19
Example: Directions from Current Location .................................................................................. 19
Example: Calculating Trip Cost ........................................................................................................... 20
Example: Stopping Pattern ................................................................................................................... 23
Example: Journey Coordinates ............................................................................................................ 24
Example: Service Alerts ......................................................................................................................... 27
Example: Wheelchair Accessibility .................................................................................................... 28
Example: Querying For Only Wheelchair-Accessible Journeys .............................................. 30
1.4.
Departure API .................................................................................................................................... 30
Example: Listing All Upcoming Departures ................................................................................... 31
Example: Departures from a Specific Platform ............................................................................. 32
1.5.
Service Alert API ............................................................................................................................... 33
Example: Retrieving Active Alerts For Today ............................................................................... 33
Example: Retrieving Alerts for a Specific Stop .............................................................................. 34
Trip Planner APIs: Technical Documentation
2
1.6.
Coordinate Request API ................................................................................................................. 35
Example: Finding Opal Ticket Resellers .......................................................................................... 35
Author:
Transport for NSW
Date:
Juny 2018
Version:
3.1
Internal Ref
G:\GIS\TND\!_File Exchange\Real-time\Data Dictionary and Real Time Release Notes
Trip Planner APIs: Technical Documentation
3
1. Transport for NSW API
This document describes the Transport for NSW Trip Planner APIs. It is intended to
complement the TfNSW Open Data Trip Planner API Swagger Documentation.
1.1.
Introduction
The API allows users to search for trips, stops, service alerts and places of interest using the
following five request types:
1.
2.
3.
4.
5.
Stop Finder API: Provides capability to return all NSW public transport stop, station, wharf,
points of interest and known addresses to be used for auto-suggest/auto-complete (to be
used with the Trip planner and Departure board APIs).
Trip Planner API: Provides capability to provide NSW public transport trip plan options,
including walking and driving legs, real-time and Opal fare information.
Departure API: Provides capability to provide NSW public transport departure information
from a stop, station or wharf including real-time.
Service Alert API: Provides capability to display all public transport service status and
incident information (as published from the Incident Capture System).
Coordinate Request API: When given a specific geographical location, this API finds
public transport stops, stations, wharfs and points of interest around that location.
Each of these calls performs complementary functions so that you can combine them to make a
comprehensive trip planner for the New South Wales public transportation network.
This document discusses each of the API calls in greater depth than the TfNSW Open Data
Swagger documentation and demonstrates realistic usage examples to help you make effective
use of the API.
A Note about Usage Examples
In the Getting Started chapter there are two ways presented for accessing the API data:
accessing JSON response data directly, or using the TfNSW Open Data Swagger
documentation to build a client library using your development language.
The usage examples in this manual will use PHP code directly accessing the JSON response
data. This makes the examples easier to comprehend for non-PHP users than if we worked with
a client library generated for PHP using the Swagger documentation.
A Note about Caching
In this document we don’t discuss caching strategies (as in, saving response data for frequently
used requests to speed up improvement of your web site or app). Since trip planning data can
update frequently (e.g. daily, depending on the route or its operator), you may not want to cache
such responses at all.
However, other API calls - such as retrieving Opal resellers using the Coordinate Request API won’t update their data as frequently. You may want to cache such data for a short period of
time, as this will improve the performance of your applications and improve the user experience.
Trip Planner APIs: Technical Documentation
4
It is important to consider the type of data you want to cache to ensure stale data is never
presented to your users.
A Note about Response Data
In order to retrieve response data in the format covered by this manual and the corresponding
Swagger documentation, you must include a request parameter called outputFormat with a
value of rapidJSON. The Getting Started chapter discusses JSON in further detail.
In order to retrieve coordinates in the standard format (EPSG 4326) that services such as
Google Maps, or many modern programming languages use, you must include a request
parameter called coordOutputFormat with a value of EPSG:4326. This is true for all API calls in
the TfNSW API.
Getting Started
The API returns responses in JSON format. There are primarily two ways you can
programmatically handle these responses:
1.
Manually build request URLs, then perform the HTTP request, then parse the returned
JSON data manually in accordance with the TfNSW Open Data Swagger Documentation.
This takes more work but gives you full control of how the data is handled.
2.
Use swagger-codegen to generate usable code in your language of choice. This is a
simpler way to get up and running with the API, especially for handling future versions of
the API, where the response data format may have changed.
JSON
All API calls return JSON data. JSON (an acronym for JavaScript Object Notation - although it is
not specific to JavaScript at all), is a lightweight data-interchange format that is made up of the
following six types of data:
•
Strings (e.g. "Hello")
•
Numbers (e.g. 1.5 or 67)
•
Booleans (true or false)
•
Null (empty value)
•
Arrays (an ordered collection of zero or more of any of these six types, e.g. [ "Hello",
1.5, false ])
•
Objects (a unordered collection of zero or more of any of these six types, each accessible
using a unique string key, e.g. { name: 'Mary' }).
This is an extremely simplified introduction to JSON, but you should be familiar with JSON if you
are using this API.
Trip Planner APIs: Technical Documentation
5
All API calls to the TfNSW Trip Planner APIs must include a URL parameter called
outputFormat with a value of rapidJSON. This is used to enable the JSON output mode.
Manually Performing Requests and Handling Responses
You can manually perform HTTP requests in the language of your choice and the handle the
response manually. In this case, you would need to create the request URL manually and then
parse the JSON response accordingly.
For example, in PHP you could perform a Stop Finder request as follows:
Note: the following example is very basic and doesn’t handle errors such as network connectivity
issues or validate response data. If you’re using using PHP to perform API requests, it is
recommended you use the cURL functions instead.
'rapidJSON',
'type_sf'
=> 'any',
'name_sf'
=> 'Circular Quay',
'coordOutputFormat' => 'EPSG:4326',
'anyMaxSizeHitList' => 10
);
$url = $apiEndpoint . $apiCall . '?' . http_build_query($params);
$response = file_get_contents($url);
Assuming this response is a valid JSON response, you can access the data by converting it into
a native JSON data structure then extracting the data you require. The following example shows
how to output the name from each returned location from the above request.
tfnswStopfinderRequest(
'rapidJSON',
'any',
'Circular Quay',
Trip Planner APIs: Technical Documentation
7
);
'EPSG:4326',
10
} catch (Exception $e) {
echo 'Exception: ', $e->getMessage(), "\n";
exit(1);
}
$locations = $result->getLocations();
foreach ($locations as $location) {
echo $location->getName() . "\n";
}
Note: In this particular case, the PHP client library improves error handling by using exception
handlers. Additionally, you do not need to specify the API endpoints (URLs), since these are read
from the Swagger specification.
If your development environment includes code auto completion, it is much easier to discover
which response values are available, compared to manually parsing the JSON data yourself.
Data Handling: On Demand Bus
On Demand services allow you to book a vehicle to pick you up from home or a convenient
nearby location, and take you to a local transport hub or point of interest. Bookings for services
are dealt with directly by each On Demand Transport Operator using an app, online or by
phone.
From 1-Jul-2018 onwards, On Demand services will be returned by the Trip Planner APIs. The
API results contain indicative trips (not actual trips) which are intended to raise awareness to the
services and direct the customer to the appropriate channel for booking an actual trip.
Due to the indicative nature of the trip plan results, special handling is required:
Display an area zone (polygon), and removal of the route path shape (line path) for the
On Demand leg of a journey – see below
Trips returned are indicative of service availability in terms of time-of-day and day-ofweek, but actual departure and arrival times will vary once the service is booked by the
customer
Product to be labeled as “On Demand” (where applicable)
An On Demand icon used to designate the service (where applicable)
Trip Planner APIs: Technical Documentation
8
A label/badge indicating that booking is required to use the service (where applicable)
Identifying an On Demand Service
On Demand services in the trip planner results are identified by transportation:iconId:23 –
refer to JSON response snippet below for an example:
"transportation": {
"id": "nsw:95D90: :R:sj2",
"name": "On demand D90",
"disassembledName": "D90",
"number": "D90",
"iconId": 23,
"description": "On Demand - Bankstown",
"product": {
"class": 5,
"name": "On demand",
"iconId": 5
},
Area Zone (polygon) replaces the Route Path Shape
The route path shape (route line) returned by the API is not to be displayed to customers in
response to their trip plan. For the On Demand leg of a trip, a zone (polygon) should be
displayed to the customer which indicates the coverage area of the particular service.
The zone shape is obtained by consuming the Open Data On Demand GTFS. Zones are
contained in the areas.txt file (based off the GTFS Flex standard) and are linked to trips.txt
through the area_id field. Further details on how to consume and use the GTFS are
contained with the On Demand GTFS release notes.
1.2.
Stop Finder API
The Stop Finder API (also known as stop_finder) is used to search for stops, places of
interest, or other locations you can travel between on the TfNSW network. Unlike coord, you
search based on names or IDs instead of a single coordinate.
The primary use-case for this API call is so users can find a starting or finishing location for a
trip planning request (performing trip planning requests is covered in the chapter about trip).
If multiple locations are returned, each location can be presented to the user so they can then
manually choose (either on a map or by its title) the location they are looking for. Each location
Trip Planner APIs: Technical Documentation
9
has a corresponding unique identifier that can be used in other API calls to reference the given
location.
Example: Searching for a Stop
Consider the scenario where somebody flies from Melbourne to Sydney and wants to travel
from the domestic airport to Circular Quay.
In this situation, two searches would be needed: one for the airport station and another for
Circular Quay.
Assuming the user is presented a search form, into which they simply entered Airport, let’s
say their input is in the $searchQuery variable.
'rapidJSON',
'odvSugMacro'
=> 1
'name_sf'
=> $searchQuery,
'coordOutputFormat' => 'EPSG:4326',
'TfNSWSF'
=> 'true'
);
$url = $apiEndpoint . $apiCall . '?' . http_build_query($params);
// Perform the request and build the JSON response data
$response = file_get_contents($url);
$json = json_decode($response, true);
// Extract locations from response
$locations = $json['locations'];
// This will hold the best match that is returned
$bestMatch = null;
foreach ($locations as $location) {
// Only one returned location will have isBest set to true
if ($location['isBest']) {
$bestMatch = $location;
break;
Trip Planner APIs: Technical Documentation
10
}
}
if (is_null($bestMatch)) {
// No best match found
}
else {
// Location ID of 10101331
$locationId = $location['id'];
// Location Name of "Sydney Domestic Airport Station, Mascot"
$name = $location['name'];
}
// ... Do something with the location
The API returns a value called matchQuality which indicates how well the location matches
the search term. Additionally, the value for isBest is set to true for the returned location with
the highest matchQuality score.
Since many locations were returned, you may instead want to allow the user to choose which
location to use. In this case, you may want to sort the return locations by their matchQuality
score (the higher the better).
You can then repeat this entire process again for the destination location (in this example,
Circular Quay). Once this is complete, you will have a stop ID for both the origin and destination.
You can subsequently use these IDs in a call to the Trip Planner API.
Location Types
Each location returned by stop_finder has a corresponding location type. It is important to
handle each location type accordingly, as the data made available with the location is
dependent upon its location type.
For example, if the type value is stop, then the location will include an array called modes,
which indicates the modes of transport that service the stop.
'rapidJSON',
'type_sf'
=> 'stop',
'name_sf'
=> '10101331',
'coordOutputFormat' => 'EPSG:4326',
'anyMaxSizeHitList' => 10,
'TfNSWSF'
=> 'true'
);
// Perform the request and handle the response
This query will subsequently return information about the domestic airport station.
Extracting Address Parts
The stop_finder API call can also return information about places of interest or specific
Street addresses. In other words, users don’t need to search for a specific stop.
Trip Planner APIs: Technical Documentation
12
In this instance, just update the name_sf request parameter accordingly.
Also, consider that many street names are used multiple suburbs, so it is especially important in
this case to ask the user which of the matching locations they want. For example, a search of 1
Main Road may return 10 or 20 locations.
When prompting a user which location they want, it’s important to disambiguate between the
results. You can use the name value to provide the suburb name, or you can manually build up
the street address using type, streetName, buildingNumber, parent, and any other
fields you think may be useful.
'rapidJSON',
'coordOutputFormat' => 'EPSG:4326',
'depArrMacro'
=> 'dep',
'itdDate'
=> date('Ymd', $when),
'itdTime'
=> date('Hi', $when),
'type_origin'
=> 'stop',
'name_origin'
=> $origin,
'type_destination' => 'stop',
'name_destination' => $destination,
'TfNSWTR'
=> 'true'
);
There are four primary inputs that are necessary for a Trip Planner API request:
1.
2.
3.
4.
Origin location
Destination location
Date/time of search (this is set to “now” in this example)
Whether the query is “depart after” or “arrive before”, (indicated by either dep or arr in
the depArrMacro request parameter).
In this example, the native PHP date() function is used to format the timestamp into a valid
date and time for the request (populated into itdDate and itdTime respectively).
Trip Planner APIs: Technical Documentation
15
The following code continues from the above, now performing the request and building a
summary of results.
", $summary) . "\n\n";
This example will produce output similar to the following:
Mon, 17 Oct 2016 15:14:00 +1100 - Mon, 17 Oct 2016 15:40:00
+1100 (39 mins)
Train -> Ferry
Mon, 17 Oct 2016 15:14:00 +1100 - Mon, 17 Oct 2016 15:43:00
+1100 (61 mins)
Train -> Walk -> Bus
Mon, 17 Oct 2016 15:20:00 +1100 - Mon, 17 Oct 2016 16:20:00
Trip Planner APIs: Technical Documentation
17
+1100 (55 mins)
Train -> Train -> Walk -> Bus -> School Bus -> Bus
Note that this example does not use real-time data. The next example shows how to make use
of real-time data.
Example: Real-Time Data
By including the TfNSWTR parameter with a value of true, you enable the ability for real-time
data to be returned.
contained
within
the
departureTimeEstimated
arrivalTimeEstimated fields of a stop sequence element.
Real-time
data
is
and
Each public transport leg (i.e. not walking or driving) includes an element called
stopSequence. This contains an ordered list of stops where the vehicle stops. This includes
the first and last stop, which are also available from the origin and destination values
within a journey leg.
Note: The origin stop will typically only include departure times, while the destination stop will
typically only include arrival times. Stops in-between may include both arrival and departure
times, since they may differ if a vehicle has a layover at a stop.
The following example shows how to read the scheduled and estimated arrival from a journey
leg. The same can be done for the arrival time using the arrivalTimeEstimated and
arrivalTimePlanned values.
0) {
$departureIsRealtime = true;
$departure = strtotime($departureEstimate);
}
Trip Planner APIs: Technical Documentation
18
else {
$departure = strtotime($departurePlanned);
}
// ... Do something with the estimate
}
Note: The method used here to ensure the departure time is somewhat crude. You may want
perform your own validation to ensure it’s a useable timestamp, or whether to fall back to the
scheduled time.
Example: Arrive By
As noted in the above example, you can either search for trips either “departing after” or
“arriving before” the given time.
•
•
Depart After: If the user wants to leave right now, you would use a “depart after” query. All
returned journeys would depart no earlier than this time. The results are sorted by their
departure time (earliest first).
Arrive Before: If the user wants to arrive at their destination by, say, 6 PM, you would use
an “arrive before” query. All returned journeys would arrive no later than this time. The
results are sorted by their arrival time (latest first - that is, closest to the arrival time first).
To make use of this in trip, it’s just a matter of using arr in the depArrMacro request
parameter.
'arr',
'itdDate'
=> date('Ymd', $when),
'itdTime'
=> date('Hi', $when),
...
);
Performing the request and handling the response data is identical to before, except that
returned journeys are sorted in reverse order.
Example: Directions from Current Location
If you’re developing a mobile app that uses the trip API call, a common use-case is to display
directions from the user’s current location (determined using GPS functionality on their device).
Trip Planner APIs: Technical Documentation
19
In this instance, you would use this coordinate as the origin location (the name_origin field).
Additionally, specify the type_origin value as coord.
Note: Of course, you can also use a coordinate as the destination location - just use
name_destination and type_destination instead.
The format for specifying a coordinate is LONGITUDE:LATITUDE:EPSG:4326. For
example, if you have determined the user’s location is (-33.884080, 151.206290),
then the name_origin value would be 151.206290:-33.884080:EPSG:4326.
$coord,
'type_origin' => 'coord'
...
);
It is highly likely that for such a request that the first leg of the returned journeys is a walking leg,
since the origin location isn’t necessarily a stop or station.
Example: Calculating Trip Cost
The trip API call includes - when available - information about the cost of each returned
journey. Since calculating an Opal fare is quite complex (there are many factors that determine
a trip cost), using the data provided from this API call is very useful.
The following code shows how to extract the fare information from a journey. This example only
keeps ADULT fares and discards the remaining fare information.
$coord[0],
'lng' => $coord[1]
);
}
?>
// Output JavaScript code while looping over response legs
// This is a shortcut to output a PHP array to JavaScript code
var coords = ;
Trip Planner APIs: Technical Documentation
25
var path = new google.maps.Polyline({
path: coords,
geodesic: true,
strokeColor: '#FF0000', // Red line
strokeOpacity: 1.0,
strokeWeight: 2
});
// This assumes `map` has been configured
// previously to a `google.maps.Map` object.
path.setMap(map);
$origin['coord'][0],
'lng' => $origin['coord'][1]
);
?>
$destinationCoord = array(
'lat' => $destination['coord'][0],
'lng' => $destination['coord'][1]
);
// Output JavaScript code while looping over response legs
// This is a shortcut to output a PHP object to JavaScript code
var origin = ;
Trip Planner APIs: Technical Documentation
26
var originMarker = new google.maps.Marker({
position: origin,
map: map,
title:
});
var destination = ;
var destinationMarker = new google.maps.Marker({
position: destination,
map: map,
title:
});
'on'
...
);
1.4.
Departure API
The Departure API (also known as departure_mon) is used to find upcoming departures at a
given stop.
Trip Planner APIs: Technical Documentation
30
The primary use-case for this API call is to display a “departure board” type interface where you
can quickly see which services are about to depart and where they are going to.
Note:
On Demand Bus services may be returned by the Departure API, depending on the
customer stop/TSN criteria. Refer to the Data Handling On Demand Bus section of this
document for special handling of these results.
Example: Listing All Upcoming Departures
The following example shows how to request all upcoming departures for Domestic Airport
Station (specified by stop ID 10101331).
It uses “now” (indicated by time() in PHP) as the search date. The format string of Ymd in
PHP will create a YYYYMMDD formatted date. Likewise, a format string of Hi creates a time in
HHMM 24-hour format.
The comments in the code indicate how to use the returned data.
'rapidJSON',
'coordOutputFormat' => 'EPSG:4326',
'mode'
=> 'direct',
'type_dm'
=> 'stop',
'name_dm'
=> $stop,
'depArrMacro'
=> 'dep',
'itdDate'
=> date('Ymd', $when),
'itdTime'
=> date('Hi', $when),
'TfNSWDM'
=> 'true'
);
$url = $apiEndpoint . $apiCall . '?' . http_build_query($params);
// Perform the request and build the JSON response data
$response = file_get_contents($url);
$json = json_decode($response, true);
Trip Planner APIs: Technical Documentation
31
$stopEvents = $json['stopEvents'];
// Loop over returned stop events
foreach ($stopEvents as $stopEvent) {
// Extract the route information
$transportation = $stopEvent['transportation'];
$routeNumber = $transportation['number'];
$destination = $transportation['destination']['name'];
// In the case of a train, the location includes platform information
$location = $stopEvent['location'];
// Determine how many minutes until departure
$time = strtotime($stopEvent['departureTimePlanned']);
$countdown = $time - time();
$minutes = round($countdown / 60);
}
// Output the stop event with a countdown timer
echo $minutes . "m from " . $location['disassembledName'] . "\n";
echo $routeNumber . " to " . $destination . "\n\n";
This example creates a crude departure board that lists all returned departure times.
Additionally, it calculates and displays how many minutes until the departure is and includes that
information.
Example: Departures from a Specific Platform
In the above example, all departures from Domestic Airport Station are included. If you only
wanted to list departures from platform 1 of this station, you would change the value name_dm
to the ID for the platform, and then set nameKey_dm to $USEPOINT$.
'rapidJSON',
'coordOutputFormat' => 'EPSG:4326',
'mode'
=> 'direct',
'type_dm'
=> 'stop',
'name_dm'
=> $stop,
'nameKey_dm'
=> '$USEPOINT$',
Trip Planner APIs: Technical Documentation
32
);
'depArrMacro'
=> 'dep',
'itdDate'
=> date('Ymd', $when),
'itdTime'
=> date('Hi', $when),
'TfNSWDM'
=> 'true'
// ...
If you were to output the results of this query as above, you would notice the returned results
are all from the same platform.
1.5.
Service Alert API
The Service Alert API (also known as add_info) is used to retrieve service alert information.
The primary use-case for this API call is to determine any outages, delays, or other information
that is pertinent to users of the public transportation network.
Example: Retrieving Active Alerts For Today
The following example shows how to retrieve active alerts for the current day.
This is achieved by specifying the filterDateValid value with a timestamp formatted in
DD-MM-YYYY format. Additionally, by specifying the filterPublicationStatus with a
value of current, historical alerts are not returned (i.e. alerts that are no longer active),
making the response data smaller.
'rapidJSON',
'coordOutputFormat'
=> 'EPSG:4326',
'filterDateValid'
=> date('d-m-Y', $when),
'filterPublicationStatus' => 'current'
);
$url = $apiEndpoint . $apiCall . '?' . http_build_query($params);
// Perform the request and build the JSON response data
$response = file_get_contents($url);
$json = json_decode($response, true);
Trip Planner APIs: Technical Documentation
33
$infos = $json['infos'];
$current = $infos['current'];
// Loop over found messages
foreach ($current as $message) {
// Extract heading and URL for alert
$heading = $message['subtitle'];
$url = $message['url'];
// Determine how long since alert modified
$timestamps = $message['timestamps'];
$modified = strtotime($timestamps['lastModification']);
$age
= time() - $modified;
$hr = round($age / 3600);
$min = round($age / 60) % 60;
echo strtoupper($heading) . "\n";
echo sprintf("Last Modified: %s (%dh %dm ago)\n", date('r', $modified), $hr, $min);
echo "More Info: " . $url . "\n";
// Extract info about affected routes and stops
$affected = $message['affected'];
$lines = $affected['lines'];
$stops = $affected['stops'];
}
echo "Affected Stops: " . count($stops) . "\n";
echo "Affected Lines: " . count($lines) . "\n\n";
This example shows how to extract various data from the alert. Refer to the Swagger
documentation for a comprehensive list of all data available.
For instance, the stops and lines that are impacted by the alert are included also. This includes
information about route / stop number and titles.
Example: Retrieving Alerts for a Specific Stop
It is possible with add_info to retrieve alerts only for a particular stop by specifying the
itdLPxx_selStop request parameter.
The following example shows how to retrieve today’s current alerts that are relevant to Central
Station (which has a stop ID of 10111010).
'rapidJSON',
'coordOutputFormat'
=> 'EPSG:4326',
'filterDateValid'
=> date('d-m-Y', $when),
'filterPublicationStatus' => 'current',
'itdLPxx_selStop'
=> '10111010'
);
// Perform request and process response
1.6.
Coordinate Request API
The Coordinate Request API (also known as coord) is used to find places of interest, stops or
Opal resellers near a given location (specified using a latitude/longitude coordinate).
The primary use-case for this API call is for displaying such locations on a map when users are
looking for particular locations. While the stop_finder API call finds locations when the user
knows what to search for, coord suggests locations based on an input coordinate.
In addition to specifying a coordinate from which to base the search, the request must also
include a radius (in metres), which restricts how far away from the source coordinate returned
locations are.
Increasing the radius will exponentially increase the number of the returned results, so it’s
important to be mindful of your system resources. Increasing a search radius, say from 1000m
to 2000m might overload a user’s web browser or mobile device, since the number of returned
locations could increase from, say, 100 to 10000.
Example: Finding Opal Ticket Resellers
Consider the scenario where you want to display a map of Opal resellers near the user’s
location on their iPhone or Android device.
The algorithm you would follow for doing so would be:
1.
2.
3.
4.
Determine the user’s current location (latitude and longitude).
Determine how far you want to search from that location (the search radius). This may be
based on the zoom level of the map being displayed to the user.
Perform a coord with a type_1 value of GIS_POINT and the radius in the radius_1
request parameter.
Parse results and display on map.
To specify the origin coordinate of the search, you must specify the coord request value. This
uses a format of LATITUDE:LONGITUDE:EPSG:4326.
Trip Planner APIs: Technical Documentation
35
For example, if you have determined the user’s location is (-33.884080, 151.206290),
then the coord value would be the string 151.206290:-33.884080:EPSG:4326.
Note: Be aware that coordinates are commonly written with latitude first, but the ordering is
reversed for TfNSW API request parameters such as coord, meaning longitude is first.
'rapidJSON',
'coord'
=> $coord,
'coordOutputFormat' => 'EPSG:4326',
'type_1'
=> 'GIS_POINT',
'radius_1'
=> $radius,
'inclFilter'
=> 1,
);
// Flag to ensure only Opal resellers are returned
'inclDrawClasses_1' => 74
$url = $apiEndpoint . $apiCall . '?' . http_build_query($params);
// Perform the request and build the JSON response data
$response = file_get_contents($url);
$json = json_decode($response, true);
// Extract locations from response
$locations = $json['locations'];
foreach ($locations as $location) {
// Read the name, coordinate and distance from the location
$name = $location['name'];
$coord = $location['coord'];
Trip Planner APIs: Technical Documentation
36
$lat = $coord[0];
$lon = $coord[1];
$distance = $location['properties']['distance'];
// Output information about the location
echo $distance . "m away: " . $name . "\n";
// Demonstrates how to use the coordinate.
// You may want to display on a map instead
echo sprintf(
"https://maps.google.com/?q=%01.6f,%01.6f\n\n",
$lat,
$lon
);
}
Trip Planner APIs: Technical Documentation
37
Source Exif Data:
File Type : PDF File Type Extension : pdf MIME Type : application/pdf PDF Version : 1.5 Linearized : No Page Count : 37 Language : en-AU Tagged PDF : Yes Author : Mu, Teddy Creator : Microsoft® Word 2010 Create Date : 2018:07:06 15:48:54+10:00 Modify Date : 2018:07:06 15:48:54+10:00 Producer : Microsoft® Word 2010EXIF Metadata provided by EXIF.tools