[ Whereis® API Home ] [ JSON API Home ] [ Object Index ] [ Return Types ]
Returned in response to a route or route-handle request. Describes a route in two ways: as a set of navigational instructions and in terms of its map geometry.
A <route> is one of the most complex objects handled by the API. It's format is shown at a high level; the parameter breakdown describes all parameters.
Parameters
Name | Type | Description |
handle | expanded | Identifier consisting of id and expiry |
id | string | 16 character string that can be resubmitted to routing services to obtain additional information about the route |
expiry | string | Timestamp in the format yyyy-mm-dd hh:mm:ss. The id may be used to retrieve data about this route up until the time indicated.: typically, 30 minutes from the time the route is first generated |
distance | number | Total route length in metres |
duration | int | Estimated journey time in seconds |
startPoint | <point> | Start point of the entire route ( a streetPoint corresponding to the first waypoint requested) |
endPoint | <point> | End point of the entire route (a streetPoint corresponding to the last waypoint requested) |
bounds | <bounds> | Defines an extent which encompasses the full geometry - that is, all points - in the route |
routes | [<route>] | A list of routes, being the section of travel from one waypoint to the next |
segments | expanded below | Each route within a route contains a list of segments, which is a leg of the route from one intersection to the next |
Element of Segment Array
Parameter | Type | Description |
segmentId | int | Segment identifier, numbers from 0 |
roadType | string | may be one of "MOTORWAY", "OTHER_ROAD" or "UNDEFINED" |
geometry | [[<point>]] | An array of arrays. Each embedded array is similar to a polyline, but unnamed. Usually only the first element in the outer array is populated. The first polyline describes the current segment. If other route segments extend into the bounds for this one, their polylines are also listed. The geometry of the final segment in a route (where the "STOP" manoeuvre occurs) is unpopulated. "geometry" is replaced <encodedGeometry> when a route is returned in an Optimised route by handle response. |
bounds | <bounds> | Defines an extent that encompasses the full geometry - that is, all points - in this segment |
duration | int | Estimated segment journey time in seconds |
startPoint | <point> | Start point of the current segment. For the first segment, this is the same as the startPoint of the route |
distance | number | Segment length in metres, by road |
instruction | expanded below | Describes the action to be taken at the intersection at the end of the segment |
Instruction
Parameter | Type | Description |
manoeuvre | expanded |
|
type | string | Provides a general direction for commencement of the current segment, such as "START", "STOP", "LEFT", "RIGHT", "FERRY EMBARK", "FERRY DISEMBARK", etc. |
feature |
| In future releases, this parameter will be used to identify the landmark where the manoeuvre occurs. |
street | string | Street name of the current segment |
suburb | string | Suburb name of the current segment |
originAngle | int | Number of degrees (from north) at which traveller approaches the intersection |
turnAngle | int | Number of degrees (from their heading) through which the traveller turns between entering and exiting the intersection |
destinationAngle | int | Number of degrees (from north) at which leaves the intersection |
bearing | string | A compass direction describing the direction of travel from the "startPoint" to the end of the segment |
textualInstruction | string | A plain English direction which describes the route the traveller should take at the start of this segment. Place names in the string are delimited by underscore characters. |
Example (optimised)
{
"route": {
"endPoint": {
"lat": -37.81564,
"lon": 144.97816
},
"handle": {
"id": "EUZ6p4t0gegVkcYc",
"expiry": "2012-04-12 09:01:05"
},
"routes": [
{
"endPoint": {
"lat": -37.81564,
"lon": 144.97816
},
"segments": [
{
"segmentId": 0,
"roadType": "UNDEFINED",
"encodedGeometry": [
"15,-3781563,14495817,2,8,-11,5,-54,24,-14,7,-25,11,-57,29,-15,8,-19,9,-12,6,-37,18,-56,26,-43,19,-6,3,-38,19"
],
"bounds": {
"top": -37.81561,
"left": 144.95817,
"bottom": -37.81948,
"right": 144.96009
},
"duration": 58,
"startPoint": {
"lat": -37.81563,
"lon": 144.95817
},
"distance": 466.7,
"instruction": {
"manoeuvre": {
"type": "START",
"feature": ""
},
"street": "Bourke St",
"suburb": "Melbourne",
"destinationAngle": 69.4,
"bearing": "East",
"textualInstruction": "Start at _Bourke St, Melbourne_ - proceed East"
}
},
{
"segmentId": 1,
"roadType": "OTHER_ROAD",
"encodedGeometry": [
"41,-3781948,14496009,13,49,12,42,3,11,7,29,4,12,10,34,6,19,10,34,4,15,12,41,22,76,14,50,9,30,9,32,5,17,28,99,21,72,3,13,10,35,5,14,4,13,17,58,4,13,21,79,10,35,17,55,4,12,10,29,19,68,6,20,15,51,4,13,14,49,5,16,27,92,3,11,5,14,13,45,13,47,8,28"
],
"bounds": {
"top": -37.81522,
"left": 144.96009,
"bottom": -37.81948,
"right": 144.97481
},
"duration": 171,
"startPoint": {
"lat": -37.81948,
"lon": 144.96009
},
"distance": 1376.2,
"instruction": {
"manoeuvre": {
"type": "LEFT",
"feature": ""
},
"street": "Flinders St",
"suburb": "Melbourne",
"originAngle": 158.2,
"turnAngle": -87.4,
"destinationAngle": 70.7,
"bearing": "East",
"textualInstruction": "Turn left onto _Flinders St, Melbourne_"
}
},
{
"segmentId": 2,
"roadType": "OTHER_ROAD",
"encodedGeometry": [
"8,-3781522,14497481,3,26,-14,139,-4,40,-5,45,-2,13,-2,24,-6,46"
],
"bounds": {
"top": -37.81519,
"left": 144.97481,
"bottom": -37.81552,
"right": 144.97814
},
"duration": 29,
"startPoint": {
"lat": -37.81522,
"lon": 144.97481
},
"distance": 294.7,
"instruction": {
"manoeuvre": {
"type": "VEER RIGHT",
"feature": ""
},
"street": "Wellington Pde",
"suburb": "Melbourne",
"originAngle": 70.0,
"turnAngle": 27.5,
"destinationAngle": 97.5,
"bearing": "East",
"textualInstruction": "Veer right onto _Wellington Pde, Melbourne_"
}
},
{
"segmentId": 3,
"roadType": "OTHER_ROAD",
"encodedGeometry": [
"7,-3781552,14497814,-2,7,-8,78,-4,8,-7,5,-16,1,-53,-8"
],
"bounds": {
"top": -37.81552,
"left": 144.97814,
"bottom": -37.81642,
"right": 144.97913
},
"duration": 17,
"startPoint": {
"lat": -37.81552,
"lon": 144.97814
},
"distance": 170.0,
"instruction": {
"manoeuvre": {
"type": "RIGHT",
"feature": ""
},
"street": "Jolimont Rd",
"suburb": "East Melbourne",
"originAngle": 98.8,
"turnAngle": 78.9,
"destinationAngle": 177.7,
"bearing": "South",
"textualInstruction": "Turn right onto _Jolimont Rd, East Melbourne_"
}
},
{
"segmentId": 4,
"roadType": "OTHER_ROAD",
"encodedGeometry": [
"8,-3781642,14497905,2,-10,33,5,19,4,4,-1,4,-1,4,-5,5,-13"
],
"bounds": {
"top": -37.81571,
"left": 144.97884,
"bottom": -37.81642,
"right": 144.97905
},
"duration": 9,
"startPoint": {
"lat": -37.81642,
"lon": 144.97905
},
"distance": 95.0,
"instruction": {
"manoeuvre": {
"type": "RIGHT U-TURN",
"feature": ""
},
"street": "Jolimont Rd",
"suburb": "East Melbourne",
"originAngle": 186.9,
"turnAngle": 181.1,
"destinationAngle": 7.9,
"bearing": "North",
"textualInstruction": "Make right U-Turn onto _Jolimont Rd, East Melbourne_"
}
},
{
"segmentId": 5,
"roadType": "OTHER_ROAD",
"encodedGeometry": [
"3,-3781571,14497884,4,-44,3,-24"
],
"bounds": {
"top": -37.81564,
"left": 144.97816,
"bottom": -37.81571,
"right": 144.97884
},
"duration": 6,
"startPoint": {
"lat": -37.81571,
"lon": 144.97884
},
"distance": 60.2,
"instruction": {
"manoeuvre": {
"type": "VEER LEFT",
"feature": ""
},
"street": "Wellington Pde",
"suburb": "East Melbourne",
"originAngle": 298.8,
"turnAngle": -22.8,
"destinationAngle": 276.0,
"bearing": "West",
"textualInstruction": "Veer left onto _Wellington Pde, East Melbourne_"
}
},
{
"segmentId": 6,
"roadType": "OTHER_ROAD",
"encodedGeometry": [
null
],
"duration": 0,
"startPoint": {
"lat": -37.81564,
"lon": 144.97816
},
"distance": 0.0,
"instruction": {
"manoeuvre": {
"type": "STOP",
"feature": ""
},
"street": "Wellington Pde",
"suburb": "East Melbourne",
"originAngle": 278.3,
"textualInstruction": "Stop at _Wellington Pde, East Melbourne_"
}
}
],
"bounds": {
"top": -37.81519,
"left": 144.95817,
"bottom": -37.81948,
"right": 144.97913
},
"duration": 290,
"startPoint": {
"lat": -37.81563,
"lon": 144.95817
},
"distance": 2462.7998
}
],
"bounds": {
"top": -37.81519,
"left": 144.95817,
"bottom": -37.81948,
"right": 144.97913
},
"duration": 290,
"startPoint": {
"lat": -37.81563,
"lon": 144.95817
},
"distance": 2462.7998
}
}