The Directions Result Object

When sending a directions request to the DirectionsService, you receive a response consisting of a status code, and a result, which is a DirectionsResult object.

The DirectionsResult is an object literal with a single field:

  • routes[] contains an array of DirectionsRoute objects. Each route indicates a way to get from the origin to the destination provided in the DirectionsRequest. Generally, only one route is returned for any given request, unless the request's provideRouteAlternatives field is set to true, in which, multiple routes may be returned.

Directions Routes

Note: The legacy DirectionsTrip object has been renamed DirectionsRoute. Note that a route now refers to the entire start to end journey, rather than simply a leg of a parent trip.

A DirectionsRoute contains a single result from the specified origin and destination. This route may consist of one or more legs (of type DirectionsLeg) depending on whether any waypoints were specified. As well, the route also contains copyright and warning information which must be displayed to the user in addition to the routing information.

The DirectionsRoute is an object literal with the following fields:

  • legs[] contains an array of DirectionsLeg objects, each of which contains information about a leg of the route, from two locations within the given route. A separate leg will be present for each waypoint or destination specified. (A route with no waypoints will contain exactly one DirectionsLeg.) Each leg consists of a series of DirectionSteps.
  • waypoint_order contains an array indicating the order of any waypoints in the calculated route. This array may contain an altered order if the DirectionsRequest was passed optimizeWaypoints: true.
  • overview_path contains an array of LatLngs that represent an approximate (smoothed) path of the resulting directions.
  • bounds contains a LatLngBounds indicating the bounds of the polyline along this given route.
  • copyrights contains the copyrights text to be displayed for this route. If you do not use the provided DirectionsRenderer object, you must handle and display this information yourself.
  • warnings[] contains an array of warnings to be displayed when showing these directions. If you do not use the provided DirectionsRenderer object, you must handle and display these warnings yourself.

Directions Legs

Note: The legacy DirectionsRoute object has been renamed DirectionsLeg. Note that a leg refers to a leg of a parent route.

A DirectionsLeg defines a single leg of a journey from the origin to the destination in the calculated route. For routes that contain no waypoints, the route will consist of a single "leg," but for routes that define one or more waypoints, the route will consist of one or more legs, corresponding to the specific legs of the journey.

The DirectionsLeg is an object literal with the following fields:

  • steps[] contains an array of DirectionsStep objects denoting information about each separate step of the leg of the journey.
  • distance indicates the total distance covered by this leg, as a Distance object of the following form:
    • value indicates the distance in meters
    • text contains a string representation of the distance, which by default is displayed in units as used at the origin. (For example, miles will be used for any origin within the United States.) You may override this unit system by specifically setting a UnitSystem in the original query. Note that regardless of what unit system you use, the distance.value field always contains a value expressed in meters.
    • These fields may be undefined if the distance is unknown.
  • duration indicates the total duration of this leg, as a Duration object of the following form:
    • value indicates the duration in seconds.
    • text contains a string representation of the duration.
    • These fields may be undefined if the duration is unknown.
  • start_location contains the LatLng of the origin of this leg. Because the Directions Web Service calculates directions between locations by using the nearest transportation option (usually a road) at the start and end points, start_location may be different than the provided origin of this leg if, for example, a road is not near the origin.
  • end_location contains the LatLng of the destination of this leg. Because the DirectionsService calculates directions between locations by using the nearest transportation option (usually a road) at the start and end points, end_location may be different than the provided destination of this leg if, for example, a road is not near the destination.
  • start_address contains the human-readable address (typically a street address) of the start of this leg.
  • end_address contains the human-readable address (typically a street address) of the end of this leg.

Directions Steps

A DirectionsStep is the most atomic unit of a direction's route, containing a single step describing a specific, single instruction on the journey. E.g. "Turn left at W. 4th St." The step not only describes the instruction but also contains distance and duration information relating to how this step relates to the following step. For example, a step denoted as "Merge onto I-80 West" may contain a duration of "37 miles" and "40 minutes," indicating that the next step is 37 miles/40 minutes from this step.

The DirectionsStep is an object literal with the following fields:

  • instructions contains instructions for this step within a text string.
  • distance contains the distance covered by this step until the next step, as a Distance object. (See the description in DirectionsLeg above.) This field may be undefined if the distance is unknown.
  • duration contains the typical time required to perform the step, until the next step, as a Duration object. (See the description in DirectionsLeg above.) This field may be undefined if the duration is unknown.
  • start_location contains the geocoded LatLng of the starting point of this step.
  • end_location contains the LatLng of the ending point of this step.

Inspecting DirectionsResults

The DirectionsResults components — DirectionsRoute, DirectionsLeg and DirectionsStep — may be inspected and used when parsing any directions response.

The following example plots walking directions to certain tourist attractions in New York City. We inspect the route's DirectionsStep to add markers for each step, and attach information to an InfoWindow with instructional text for that step.

Note: since we are calculating walking directions, we also display any warnings to the user in a separate <div> panel.


                

            


            

                
                
                

                    
Directions Legs

                    
A DirectionsLeg defines a single leg of a journey from the origin to the destination in the calculated route. For routes that contain no waypoints, the route will consist of a single "leg," but for routes that define one or more waypoints, the route will consist of one or more legs, corresponding to the specific legs of the journey.

                

                

                    
Directions Steps

                    
A DirectionsStep is the most atomic unit of a direction's route, containing a single step describing a specific, single instruction on the journey. E.g. "Turn left at W. 4th St." The step not only describes the instruction but also contains distance and duration information relating to how this step relates to the following step. For example, a step denoted as "Merge onto I-80 West" may contain a duration of "37 miles" and "40 minutes," indicating that the next step is 37 miles/40 minutes from this step.