In a directions request, return a more structured directions object to make custom styling easier in routing applications

[qqnluaq]

The entries in the directions list in a typical result of a 'directions' request look like:

       {
            "type": "CONTINUE",
            "text": "Continue onto Swartz Bay Ferry Terminal for 75 m (27 seconds)",
            "point": [
                -123.41091,
                48.68861
            ]
        }

The text contains at least 4 separate pieces of information:

• type of direction
• destination
• distance
• expected time

Only one of these is provided as a separate property (type). The other pieces of infomation are formatted in text and hence are made more difficult than it needs to be to format this information in an application-specific way.

Describe the solution you'd like

I want to see the other parts of the text broken out into their own properties:

       {
            "type": "CONTINUE",
            "destination": "Swartz Bay Ferry Terminal",
            "distance": 75 // always in meters
            "time": 27 // always in seconds
            "text": "Continue onto Swartz Bay Ferry Terminal for 75 m (27 seconds)",
            "point": [
                -123.41091,
                48.68861
            ]
        }

[mraross]

Great enhancement suggestion Ben, thanks. Just a couple of comments:

1. Distance can be in metric (e.g. both km and m) or imperial(e.g., both miles and feet) as specified in the distanceUnit query parameter so I would add a distanceUnit property (e.g., km, m, mi, ft) to each direction object.

2. Time can also be in hours, minutes or seconds so we might want a timeUnit as well.

[cmhodgson]

I think the intent is whatever code is making use of the time and distance values probably wants to format them (or process them) on it's own so really just one distance unit, meters or feet, based on the query params, and just seconds, always. The type parameter was added to support styling the directions with appropriate icons, right now the app only supports ferry and event icons. When I added it, I kinda expected this request to come along, eventually.

[mraross]

Agreed. As for icons, I can see an app developer using their own turn icons (e.g., left, right, straight).

[cmhodgson]

I have implemented this locally with the following changes:

• The distance will always be in the distanceUnit specified by the request, which defaults to km. This is consistent with the overall distance value for the route.
• Time is always in seconds, I've rounded to the nearest second.
• Instead of destination, which is not entirely accurate, I've chosen simply "name". This leaves it open for interpretation in the case of ferry route names, street names, or possibly other things in the future.
• One additional field which was not addressed in the initial request is that the "START" type also has a cardinal direction value, which I've called heading. Some examples below:

  {
  "type":"START",
  "name":"Latoria Rd",
  "distance":"1.798",
  "time":129,
  "heading":"EAST",
  "text":"Head east on Latoria Rd for 1.8 km (2 minutes 9 seconds)",
  "point":[-123.52989,48.41535]
  },
  {
  "type":"TURN_RIGHT",
  "name":"Arbutus Rd",
  "distance":0.511,
  "time":70,
  "text":"Turn right onto Arbutus Rd for 500 m (1 minute 10 seconds)",
  "point":[-123.30314,48.47072]
  },

[mraross]

Verified in dev