Route - Get Route Directions

Returns a route between an origin and a destination, passing through waypoints if they are specified. The route will take into account factors such as current traffic and the typical road speeds on the requested day of the week and time of day.

Information returned includes the distance, estimated travel time, and a representation of the route geometry. Additional routing information such as optimized waypoint order or turn by turn instructions is also available, depending on the options selected.

Routing service provides a set of parameters for a detailed description of vehicle-specific Consumption Model. Please check Consumption Model for detailed explanation of the concepts and parameters involved.

GET https://atlas.microsoft.com/route/directions/{format}?subscription-key={subscription-key}&api-version=1.0&query={query}
GET https://atlas.microsoft.com/route/directions/{format}?subscription-key={subscription-key}&api-version=1.0&query={query}&maxAlternatives={maxAlternatives}&alternativeType={alternativeType}&minDeviationDistance={minDeviationDistance}&arriveAt={arriveAt}&departAt={departAt}&minDeviationTime={minDeviationTime}&instructionsType={instructionsType}&language={language}&computeBestOrder={computeBestOrder}&routeRepresentation={routeRepresentation}&computeTravelTimeFor={computeTravelTimeFor}&vehicleHeading={vehicleHeading}&report={report}&sectionType={sectionType}&vehicleAxleWeight={vehicleAxleWeight}&vehicleWidth={vehicleWidth}&vehicleHeight={vehicleHeight}&vehicleLength={vehicleLength}&vehicleMaxSpeed={vehicleMaxSpeed}&vehicleWeight={vehicleWeight}&windingness={windingness}&hilliness={hilliness}&travelMode={travelMode}&avoid={avoid}&traffic={traffic}&routeType={routeType}&vehicleLoadType={vehicleLoadType}&vehicleEngineType={vehicleEngineType}&constantSpeedConsumptionInLitersPerHundredkm={constantSpeedConsumptionInLitersPerHundredkm}&currentFuelInLiters={currentFuelInLiters}&auxiliaryPowerInLitersPerHour={auxiliaryPowerInLitersPerHour}&fuelEnergyDensityInMJoulesPerLiter={fuelEnergyDensityInMJoulesPerLiter}&accelerationEfficiency={accelerationEfficiency}&decelerationEfficiency={decelerationEfficiency}&uphillEfficiency={uphillEfficiency}&downhillEfficiency={downhillEfficiency}&constantSpeedConsumptionInkWhPerHundredkm={constantSpeedConsumptionInkWhPerHundredkm}&currentChargeInkWh={currentChargeInkWh}&maxChargeInkWh={maxChargeInkWh}&auxiliaryPowerInkW={auxiliaryPowerInkW}

URI Parameters

Name In Required Type Description
format
path True

Desired format of the response. Value can be either json or xml.

windingness
query

Level of turns for thrilling route. This parameter can only be used in conjunction with routeType=thrilling.

hilliness
query

Degree of hilliness for thrilling route. This parameter can only be used in conjunction with routeType=thrilling.

travelMode
query

The mode of travel for the requested route. Note that the requested travelMode may not be available for the entire route. Where the requested travelMode is not available for a particular section, the travelMode element of the response for that section will be other. Note that travel modes bus, motorcycle, taxi and van are BETA functionality. Full restriction data is not available in all areas. In calculateReachableRange requests, the values bicycle and pedestrian must not be used

avoid
query

Specifies something that the route calculation should try to avoid when determining the route. Can be specified multiple times. Possible values: (tollRoads avoids toll roads), (motorways avoids motorways), (ferries avoids ferries), (unpavedRoads avoids unpaved roads), (carpools avoids routes that require use of carpool (HOV/ High Occupancy Vehicle) lanes), (alreadyUsedRoads avoids using the same road multiple times. Most useful in conjunction with routeType=thrilling). In calculateReachableRange requests, the value alreadyUsedRoads must not be used.

traffic
query
  • boolean

Possible values:

  • true - Do consider all available traffic information during routing
  • false - Ignore current traffic data during routing. Note that although the current traffic data is ignored during routing, the effect of historic traffic on effective road speeds is still incorporated.
routeType
query

The type of route requested.

vehicleLoadType
query

Types of cargo that may be classified as hazardous materials and restricted from some roads. Available vehicleLoadType values are US Hazmat classes 1 through 9, plus generic classifications for use in other countries. Values beginning with USHazmat are for US routing while otherHazmat should be used for all other countries. vehicleLoadType can be specified multiple times. This parameter is currently only considered for travelMode=truck.

vehicleEngineType
query

Engine type of the vehicle. When a detailed Consumption Model is specified, it must be consistent with the value of vehicleEngineType.

vehicleWeight
query
  • integer

Weight of the vehicle in kilograms.

  • It is mandatory if any of the *Efficiency parameters are set.

  • It must be strictly positive when used in the context of the Consumption Model. Weight restrictions are considered.

  • If no detailed Consumption Model is specified and the value of vehicleWeight is non-zero, then weight restrictions are considered.

  • In all other cases, this parameter is ignored.

Sensible Values : for Combustion Model : 1600, for Electric Model : 1900

constantSpeedConsumptionInLitersPerHundredkm
query
  • number
float

Specifies the speed-dependent component of consumption.

Provided as an unordered list of colon-delimited speed & consumption-rate pairs. The list defines points on a consumption curve. Consumption rates for speeds not in the list are found as follows:

  • by linear interpolation, if the given speed lies in between two speeds in the list

  • by linear extrapolation otherwise, assuming a constant (ΔConsumption/ΔSpeed) determined by the nearest two points in the list

The list must contain between 1 and 25 points (inclusive), and may not contain duplicate points for the same speed. If it only contains a single point, then the consumption rate of that point is used without further processing.

Consumption specified for the largest speed must be greater than or equal to that of the penultimate largest speed. This ensures that extrapolation does not lead to negative consumption rates.

Similarly, consumption values specified for the two smallest speeds in the list cannot lead to a negative consumption rate for any smaller speed.

The valid range for the consumption values(expressed in l/100km) is between 0.01 and 100000.0.

Sensible Values : 50,6.3:130,11.5

Note : This parameter is required for The Combustion Consumption Model.

auxiliaryPowerInLitersPerHour
query
  • number
float

Specifies the amount of fuel consumed for sustaining auxiliary systems of the vehicle, in liters per hour.

It can be used to specify consumption due to devices and systems such as AC systems, radio, heating, etc.

Sensible Values : 0.2

fuelEnergyDensityInMJoulesPerLiter
query
  • number
float

Specifies the amount of chemical energy stored in one liter of fuel in megajoules (MJ). It is used in conjunction with the **Efficiency* parameters for conversions between saved or consumed energy and fuel. For example, energy density is 34.2 MJ/l for gasoline, and 35.8 MJ/l for Diesel fuel.

This parameter is required if any **Efficiency* parameter is set.

Sensible Values : 34.2

accelerationEfficiency
query
  • number
float

Specifies the efficiency of converting chemical energy stored in fuel to kinetic energy when the vehicle accelerates (i.e. KineticEnergyGained/ChemicalEnergyConsumed). ChemicalEnergyConsumed is obtained by converting consumed fuel to chemical energy using fuelEnergyDensityInMJoulesPerLiter.

Must be paired with decelerationEfficiency.

The range of values allowed are 0.0 to 1/decelerationEfficiency.

Sensible Values : for Combustion Model : 0.33, for Electric Model : 0.66

decelerationEfficiency
query
  • number
float

Specifies the efficiency of converting kinetic energy to saved (not consumed) fuel when the vehicle decelerates (i.e. ChemicalEnergySaved/KineticEnergyLost). ChemicalEnergySaved is obtained by converting saved (not consumed) fuel to energy using fuelEnergyDensityInMJoulesPerLiter.

Must be paired with accelerationEfficiency.

The range of values allowed are 0.0 to 1/accelerationEfficiency.

Sensible Values : for Combustion Model : 0.83, for Electric Model : 0.91

uphillEfficiency
query
  • number
float

Specifies the efficiency of converting chemical energy stored in fuel to potential energy when the vehicle gains elevation (i.e. PotentialEnergyGained/ChemicalEnergyConsumed). ChemicalEnergyConsumed is obtained by converting consumed fuel to chemical energy using fuelEnergyDensityInMJoulesPerLiter.

Must be paired with downhillEfficiency.

The range of values allowed are 0.0 to 1/downhillEfficiency.

Sensible Values : for Combustion Model : 0.27, for Electric Model : 0.74

downhillEfficiency
query
  • number
float

Specifies the efficiency of converting potential energy to saved (not consumed) fuel when the vehicle loses elevation (i.e. ChemicalEnergySaved/PotentialEnergyLost).ChemicalEnergySaved is obtained by converting saved (not consumed) fuel to energy using fuelEnergyDensityInMJoulesPerLiter.

Must be paired with uphillEfficiency.

The range of values allowed are 0.0 to 1/uphillEfficiency.

Sensible Values : for Combustion Model : 0.51, for Electric Model : 0.73

constantSpeedConsumptionInkWhPerHundredkm
query
  • number
float

Specifies the speed-dependent component of consumption.

Provided as an unordered list of speed/consumption-rate pairs. The list defines points on a consumption curve. Consumption rates for speeds not in the list are found as follows:

  • by linear interpolation, if the given speed lies in between two speeds in the list

  • by linear extrapolation otherwise, assuming a constant (ΔConsumption/ΔSpeed) determined by the nearest two points in the list

The list must contain between 1 and 25 points (inclusive), and may not contain duplicate points for the same speed. If it only contains a single point, then the consumption rate of that point is used without further processing.

Consumption specified for the largest speed must be greater than or equal to that of the penultimate largest speed. This ensures that extrapolation does not lead to negative consumption rates.

Similarly, consumption values specified for the two smallest speeds in the list cannot lead to a negative consumption rate for any smaller speed.

The valid range for the consumption values(expressed in kWh/100km) is between 0.01 and 100000.0.

Sensible Values : 50,8.2:130,21.3

This parameter is required for Electric consumption model.

currentChargeInkWh
query
  • string

Specifies the current electric energy supply in kilowatt hours (kWh).

This parameter co-exists with maxChargeInkWh parameter.

The range of values allowed are 0.0 to maxChargeInkWh.

Sensible Values : 43

currentFuelInLiters
query
  • number
float

Specifies the current supply of fuel in liters.

Sensible Values : 55

vehicleMaxSpeed
query
  • integer

Maximum speed of the vehicle in km/hour. A value of 0 means that an appropriate value for the vehicle will be determined and applied during route planning. A non-zero value may be overridden during route planning.

vehicleLength
query
  • number
float

Length of the vehicle in meters. A value of 0 means that length restrictions are not considered.

vehicleHeight
query
  • number
float

Height of the vehicle in meters. A value of 0 means that height restrictions are not considered.

subscription-key
query True
  • string

Azure Maps subscription key

api-version
query True
  • string

Version number of Azure Maps API. Current version is 1.0

query
query True
  • string

The Coordinates through which the route is calculated, delimited by a colon. A minimum of two coordinates is required. The first one is the origin and the last is the destination of the route. Optional coordinates in-between act as WayPoints in the route. You can pass up to 50 WayPoints unless computeBestOrder is set to true, in which case the limit is reduced to 20.

maxAlternatives
query
  • integer

Number of desired alternative routes to be calculated. Default: 0, minimum: 0 and maximum: 5

alternativeType
query

Controls the optimality, with respect to the given planning criteria, of the calculated alternatives compared to the reference route.

minDeviationDistance
query
  • integer

All alternative routes returned will follow the reference route (see section POST Requests) from the origin point of the calculateRoute request for at least this number of meters. Can only be used when reconstructing a route. The minDeviationDistance parameter cannot be used in conjunction with arriveAt

arriveAt
query
  • string
date-time

The date and time of arrival at the destination point. It must be specified as a dateTime. When a time zone offset is not specified it will be assumed to be that of the destination point. The arriveAt value must be in the future. The arriveAt parameter cannot be used in conjunction with departAt, minDeviationDistance or minDeviationTime.

departAt
query
  • string
date-time

The date and time of departure from the origin point. Departure times apart from now must be specified as a dateTime. When a time zone offset is not specified, it will be assumed to be that of the origin point. The departAt value must be in the future in the date-time format (1996-12-19T16:39:57-08:00).

minDeviationTime
query
  • integer

All alternative routes returned will follow the reference route (see section POST Requests) from the origin point of the calculateRoute request for at least this number of seconds. Can only be used when reconstructing a route. The minDeviationTime parameter cannot be used in conjunction with arriveAt

instructionsType
query

If specified, guidance instructions will be returned. Note that the instructionsType parameter cannot be used in conjunction with routeRepresentation=none

language
query
  • string

The language parameter determines the language of the guidance messages. It does not affect proper nouns (the names of streets, plazas, etc.) It has no effect when instructionsType=coded. Allowed values are (a subset of) the IETF language tags described

computeBestOrder
query
  • boolean

Re-order the route waypoints to reduce the route length. Yields best results when used in conjunction with routeType shortest. Possible values are true or false. True computes a better order if possible, but is not allowed to be used in conjunction with maxAlternatives value greater than 0 or in conjunction with circle waypoints. The response will include the optimized waypoint indices and can be used with a maximum of 20 route waypoints. False will use the locations in the given order and not allowed to be used in conjunction with routeRepresentation none.

routeRepresentation
query

Specifies the representation of the set of routes provided as response. This parameter value can only be used in conjunction with computeBestOrder=true.

computeTravelTimeFor
query

Specifies whether to return additional travel times using different types of traffic information (none, historic, live) as well as the default best-estimate travel time.

vehicleHeading
query
  • integer

The directional heading of the vehicle in degrees starting at true North and continuing in clockwise direction. North is 0 degrees, east is 90 degrees, south is 180 degrees, west is 270 degrees. Possible values 0-359

report
query
  • string

Specifies which data should be reported for diagnosis purposes. The only possible value is effectiveSettings. Reports the effective parameters or data used when calling the API. In the case of defaulted parameters the default will be reflected where the parameter was not specified by the caller.

sectionType
query

Specifies which of the section types is reported in the route response.

For example if sectionType = pedestrian the sections which are suited for pedestrians only are returned. Multiple types can be used. The default sectionType refers to the travelMode input. By default travelMode is set to car

vehicleAxleWeight
query
  • integer

Weight per axle of the vehicle in kg. A value of 0 means that weight restrictions per axle are not considered.

vehicleWidth
query
  • number
float

Width of the vehicle in meters. A value of 0 means that width restrictions are not considered.

maxChargeInkWh
query
  • string

Specifies the maximum electric energy supply in kilowatt hours (kWh) that may be stored in the vehicle's battery.

This parameter co-exists with currentChargeInkWh parameter.

Minimum value has to be greater than or equal to currentChargeInkWh.

Sensible Values : 85

auxiliaryPowerInkW
query
  • string

Specifies the amount of power consumed for sustaining auxiliary systems, in kilowatts (kW).

It can be used to specify consumption due to devices and systems such as AC systems, radio, heating, etc.

Sensible Values : 1.7

Responses

Name Type Description
200 OK

OK

Media Types: "application/json", "application/xml"

400 Bad Request

Bad request: one or more parameters were incorrectly specified or are mutually exclusive.

Media Types: "application/json", "application/xml"

401 Unauthorized

Access denied due to invalid subscription key. Make sure to provide a valid key for an active subscription.

Media Types: "application/json", "application/xml"

403 Forbidden

Permission, capacity, or authentication issues.

Media Types: "application/json", "application/xml"

404 Not Found

Not Found: the requested resource could not be found, but it may be available again in the future.

Media Types: "application/json", "application/xml"

500 Internal Server Error

An error occurred while processing the request. Please try again later.

Media Types: "application/json", "application/xml"

Examples

GetRouteDirections

Sample Request

GET https://atlas.microsoft.com/route/directions/json?subscription-key=[subscription-key]&api-version=1.0&query=52.50931,13.42936:52.50274,13.43872

Sample Response

{
  "formatVersion": "0.0.12",
  "copyright": "Copyright 2017 TomTom International BV. All rights reserved. This navigation data is the proprietary copyright of TomTom International BV and may be used only in accordance with the terms of a fully executed license agreement entered into between TomTom International BV, or an authorised reseller and yourself. If you have not entered into such a license agreement you are not authorised to use this data in any manner and should immediately return it to TomTom International BV.",
  "privacy": "TomTom keeps information that tells us how and when you use our services. This includes information about the device you are using and the information we receive while you use the service, such as locations, routes, destinations and search queries. TomTom is unable to identify you based on the information it collects, and will not try to. TomTom uses the information for technical diagnostics, to detect fraud and abuse, to create usage reports, and to improve its services. The information is kept only for these purposes and for a limited period of time, after which it is destroyed. TomTom applies security methods based on industry standards to protect the information against unauthorised access. TomTom will not give anyone else access to the information or use it for any other purpose, unless explicitly and lawfully ordered to do so following due legal process. You can find out more at http://tomtom.com/privacy. You can contact TomTom by going to http://tomtom.com/support.",
  "routes": [
    {
      "summary": {
        "lengthInMeters": 1147,
        "travelTimeInSeconds": 162,
        "trafficDelayInSeconds": 0,
        "departureTime": "2017-09-07T16:56:58+00:00",
        "arrivalTime": "2017-09-07T16:59:40+00:00"
      },
      "legs": [
        {
          "summary": {
            "lengthInMeters": 1147,
            "travelTimeInSeconds": 162,
            "trafficDelayInSeconds": 0,
            "departureTime": "2017-09-07T16:56:58+00:00",
            "arrivalTime": "2017-09-07T16:59:40+00:00"
          },
          "points": [
            {
              "latitude": 52.50931,
              "longitude": 13.42937
            },
            {
              "latitude": 52.50904,
              "longitude": 13.42912
            },
            {
              "latitude": 52.50894,
              "longitude": 13.42904
            },
            {
              "latitude": 52.50867,
              "longitude": 13.42879
            },
            {
              "latitude": 52.5084,
              "longitude": 13.42857
            },
            {
              "latitude": 52.50791,
              "longitude": 13.42824
            },
            {
              "latitude": 52.50757,
              "longitude": 13.42772
            },
            {
              "latitude": 52.50735,
              "longitude": 13.42823
            },
            {
              "latitude": 52.5073,
              "longitude": 13.42836
            },
            {
              "latitude": 52.50573,
              "longitude": 13.43194
            },
            {
              "latitude": 52.50512,
              "longitude": 13.43336
            },
            {
              "latitude": 52.50464,
              "longitude": 13.43451
            },
            {
              "latitude": 52.5045,
              "longitude": 13.43481
            },
            {
              "latitude": 52.50443,
              "longitude": 13.43498
            },
            {
              "latitude": 52.50343,
              "longitude": 13.43737
            },
            {
              "latitude": 52.50274,
              "longitude": 13.43872
            }
          ]
        }
      ],
      "sections": [
        {
          "startPointIndex": 0,
          "endPointIndex": 15,
          "sectionType": "TRAVEL_MODE",
          "travelMode": "car"
        }
      ]
    }
  ]
}
{
  "error": {
    "code": "400 BadRequest",
    "message": "Bad request: one or more parameters were incorrectly specified or are mutually exclusive."
  }
}
{
  "error": {
    "code": "401 Unauthorized",
    "message": "Access denied due to invalid subscription key. Make sure to provide a valid key for an active subscription."
  }
}
{
  "error": {
    "code": "403 Forbidden",
    "message": "Permission, capacity, or authentication issues."
  }
}
{
  "error": {
    "code": "404 NotFound",
    "message": "Not Found: the requested resource could not be found, but it may be available again in the future."
  }
}
{
  "error": {
    "code": "500 InternalServerError",
    "message": "An error occurred while processing the request. Please try again later."
  }
}

Definitions

AlternativeRouteType

Controls the optimality, with respect to the given planning criteria, of the calculated alternatives compared to the reference route.

Avoid

Specifies something that the route calculation should try to avoid when determining the route. Can be specified multiple times. Possible values: (tollRoads avoids toll roads), (motorways avoids motorways), (ferries avoids ferries), (unpavedRoads avoids unpaved roads), (carpools avoids routes that require use of carpool (HOV/ High Occupancy Vehicle) lanes), (alreadyUsedRoads avoids using the same road multiple times. Most useful in conjunction with routeType=thrilling). In calculateReachableRange requests, the value alreadyUsedRoads must not be used.

ComputeTravelTimeFor

Specifies whether to return additional travel times using different types of traffic information (none, historic, live) as well as the default best-estimate travel time.

Coordinate

A location represented as a latitude and longitude.

DrivingSide

Indicates left-hand vs. right-hand side driving at the point of the maneuver.

Error

This object is returned when an error occurs in the Maps API

ErrorResponse

This response object is returned when an error occurs in the Maps API

GuidanceInstructionType

Type of the instruction, e.g., turn or change of road form.

GuidanceManeuver

A code identifying the maneuver.

Hilliness

Degree of hilliness for thrilling route. This parameter can only be used in conjunction with routeType=thrilling.

MagnitudeOfDelay

The magnitude of delay caused by the incident. These values correspond to the values of the response field of the Get Traffic Incident Detail API.

RouteDirectionsResponse

This object is returned from a successful Route Directions call

RouteDirectionsResult
RouteDirectionsSummary

Summary object

RouteInstructionsType

If specified, guidance instructions will be returned. Note that the instructionsType parameter cannot be used in conjunction with routeRepresentation=none

RouteOptimizedWaypoint

Optimized way point object.

RouteRepresentation

Specifies the representation of the set of routes provided as response. This parameter value can only be used in conjunction with computeBestOrder=true.

RouteResponseReport

Reports the effective settings used in the current call.

RouteResponseReportEffectiveSetting

Effective parameter or data used when calling this Route API.

RouteResultGuidance

Contains guidance related elements. This field is present only when guidance was requested and is available.

RouteResultInstruction

A set of attributes describing a maneuver, e.g. 'Turn right', 'Keep left', 'Take the ferry', 'Take the motorway', 'Arrive'.

RouteResultInstructionGroup

Groups a sequence of instruction elements which are related to each other. The sequence range is constrained with firstInstructionIndex and lastInstructionIndex. When human-readable text messages are requested for guidance (instructionType=text or tagged), then the instructionGroup has a summary message returned when available.

RouteResultLeg
RouteResultLegSummary

Summary object for route section.

RouteResultSection
RouteResultSectionTec

Details of the traffic event, using definitions in the TPEG2-TEC standard. Can contain and elements.

RouteResultSectionTecCause

The cause of the traffic event. Can contain and elements. Can be used to define iconography and descriptions.

RouteType

The type of route requested.

SectionType

Specifies which of the section types is reported in the route response.

For example if sectionType = pedestrian the sections which are suited for pedestrians only are returned. Multiple types can be used. The default sectionType refers to the travelMode input. By default travelMode is set to car

TextFormat

Desired format of the response. Value can be either json or xml.

TravelMode

The mode of travel for the requested route. Note that the requested travelMode may not be available for the entire route. Where the requested travelMode is not available for a particular section, the travelMode element of the response for that section will be other. Note that travel modes bus, motorcycle, taxi and van are BETA functionality. Full restriction data is not available in all areas. In calculateReachableRange requests, the values bicycle and pedestrian must not be used

VehicleEngineType

Engine type of the vehicle. When a detailed Consumption Model is specified, it must be consistent with the value of vehicleEngineType.

VehicleLoadType

Types of cargo that may be classified as hazardous materials and restricted from some roads. Available vehicleLoadType values are US Hazmat classes 1 through 9, plus generic classifications for use in other countries. Values beginning with USHazmat are for US routing while otherHazmat should be used for all other countries. vehicleLoadType can be specified multiple times. This parameter is currently only considered for travelMode=truck.

Windingness

Level of turns for thrilling route. This parameter can only be used in conjunction with routeType=thrilling.

AlternativeRouteType

Controls the optimality, with respect to the given planning criteria, of the calculated alternatives compared to the reference route.

Name Type Description
anyRoute
  • string

Allow any alternative route to be returned irrespective of how it compares to the reference route in terms of optimality.

betterRoute
  • string

Return an alternative route only if it is better than the reference route according to the given planning criteria.

Avoid

Specifies something that the route calculation should try to avoid when determining the route. Can be specified multiple times. Possible values: (tollRoads avoids toll roads), (motorways avoids motorways), (ferries avoids ferries), (unpavedRoads avoids unpaved roads), (carpools avoids routes that require use of carpool (HOV/ High Occupancy Vehicle) lanes), (alreadyUsedRoads avoids using the same road multiple times. Most useful in conjunction with routeType=thrilling). In calculateReachableRange requests, the value alreadyUsedRoads must not be used.

Name Type Description
alreadyUsedRoads
  • string

Avoids using the same road multiple times. Most useful in conjunction with routeType=thrilling.

carpools
  • string

Avoids carpools

ferries
  • string

Avoids ferries

motorways
  • string

Avoids motorways

tollRoads
  • string

Avoids toll roads.

unpavedRoads
  • string

Avoids unpaved roads

ComputeTravelTimeFor

Specifies whether to return additional travel times using different types of traffic information (none, historic, live) as well as the default best-estimate travel time.

Name Type Description
all
  • string

Computes travel times for all types of traffic information and specifies all results in the fields noTrafficTravelTimeInSeconds, historicTrafficTravelTimeInSeconds and liveTrafficIncidentsTravelTimeInSeconds being included in the summaries in the route response.

none
  • string

Does not compute additional travel times.

Coordinate

A location represented as a latitude and longitude.

Name Type Description
latitude
  • number

Latitude property

longitude
  • number

Longitude property

DrivingSide

Indicates left-hand vs. right-hand side driving at the point of the maneuver.

Name Type Description
LEFT
  • string

Left side.

RIGHT
  • string

Right side.

Error

This object is returned when an error occurs in the Maps API

Name Type Description
code
  • string

The HTTP status code.

message
  • string

If available, a human readable description of the error.

ErrorResponse

This response object is returned when an error occurs in the Maps API

Name Type Description
error

This object is returned when an error occurs in the Maps API

GuidanceInstructionType

Type of the instruction, e.g., turn or change of road form.

Name Type Description
DIRECTION_INFO
  • string

Direction information.

LOCATION_ARRIVAL
  • string

Arrival location.

LOCATION_DEPARTURE
  • string

Departure location.

LOCATION_WAYPOINT
  • string

Way point location.

ROAD_CHANGE
  • string

Road Change.

TURN
  • string

Turn.

GuidanceManeuver

A code identifying the maneuver.

Name Type Description
ARRIVE
  • string

You have arrived.

ARRIVE_LEFT
  • string

You have arrived. Your destination is on the left.

ARRIVE_RIGHT
  • string

You have arrived. Your destination is on the right.

BEAR_LEFT
  • string

Bear left.

BEAR_RIGHT
  • string

Bear right.

DEPART
  • string

Leave.

ENTER_FREEWAY
  • string

Take the freeway.

ENTER_HIGHWAY
  • string

Take the highway.

ENTER_MOTORWAY
  • string

Take the motorway.

ENTRANCE_RAMP
  • string

Take the ramp.

FOLLOW
  • string

Follow.

KEEP_LEFT
  • string

Keep left.

KEEP_RIGHT
  • string

Keep right.

MAKE_UTURN
  • string

Make a U-turn.

MOTORWAY_EXIT_LEFT
  • string

Take the left exit.

MOTORWAY_EXIT_RIGHT
  • string

Take the right exit.

ROUNDABOUT_BACK
  • string

Go around the roundabout.

ROUNDABOUT_CROSS
  • string

Cross the roundabout.

ROUNDABOUT_LEFT
  • string

At the roundabout take the exit on the left.

ROUNDABOUT_RIGHT
  • string

At the roundabout take the exit on the right.

SHARP_LEFT
  • string

Turn sharp left.

SHARP_RIGHT
  • string

Turn sharp right.

STRAIGHT
  • string

Keep straight on.

SWITCH_MAIN_ROAD
  • string

Switch to the main road.

SWITCH_PARALLEL_ROAD
  • string

Switch to the parallel road.

TAKE_EXIT
  • string

Take the exit.

TAKE_FERRY
  • string

Take the ferry.

TRY_MAKE_UTURN
  • string

Try to make a U-turn.

TURN_LEFT
  • string

Turn left.

TURN_RIGHT
  • string

Turn right.

WAYPOINT_LEFT
  • string

You have reached the waypoint. It is on the left.

WAYPOINT_REACHED
  • string

You have reached the waypoint.

WAYPOINT_RIGHT
  • string

You have reached the waypoint. It is on the right.

Hilliness

Degree of hilliness for thrilling route. This parameter can only be used in conjunction with routeType=thrilling.

Name Type Description
high
  • string

high

low
  • string

low

normal
  • string

normal

MagnitudeOfDelay

The magnitude of delay caused by the incident. These values correspond to the values of the response field of the Get Traffic Incident Detail API.

Name Type Description
0
  • string

Unknown.

1
  • string

Minor.

2
  • string

Moderate.

3
  • string

Major.

4
  • string

Undefined, used for road closures and other indefinite delays.

RouteDirectionsResponse

This object is returned from a successful Route Directions call

Name Type Description
copyright
  • string

Copyright property

formatVersion
  • string

Format Version property

optimizedWaypoints

Optimized way points array

privacy
  • string

Privacy property

report

Reports the effective settings used in the current call.

routes

Routes array

RouteDirectionsResult

Name Type Description
guidance

Contains guidance related elements. This field is present only when guidance was requested and is available.

legs

Legs array

sections

Sections array

summary

Summary object

RouteDirectionsSummary

Summary object

Name Type Description
arrivalTime
  • string

Arrival Time property

departureTime
  • string

Departure Time property

lengthInMeters
  • integer

Length In Meters property

trafficDelayInSeconds
  • integer

Traffic Delay In Seconds property

travelTimeInSeconds
  • integer

Travel Time In Seconds property

RouteInstructionsType

If specified, guidance instructions will be returned. Note that the instructionsType parameter cannot be used in conjunction with routeRepresentation=none

Name Type Description
coded
  • string

Returns raw instruction data without human-readable messages.

tagged
  • string

Returns raw instruction data with tagged human-readable messages to permit formatting.

text
  • string

Returns raw instructions data with human-readable messages in plain text.

RouteOptimizedWaypoint

Optimized way point object.

Name Type Description
optimizedIndex
  • integer

Optimized way point index from the system.

providedIndex
  • integer

Way point index provided by the user.

RouteRepresentation

Specifies the representation of the set of routes provided as response. This parameter value can only be used in conjunction with computeBestOrder=true.

Name Type Description
none
  • string

Includes only the optimized waypoint indices but does not include the route geometry in the response.

polyline
  • string

Includes route geometry in the response.

RouteResponseReport

Reports the effective settings used in the current call.

Name Type Description
effectiveSettings

Effective parameters or data used when calling this Route API.

RouteResponseReportEffectiveSetting

Effective parameter or data used when calling this Route API.

Name Type Description
key
  • string

Name of the parameter used.

value
  • string

Value of the parameter used.

RouteResultGuidance

Contains guidance related elements. This field is present only when guidance was requested and is available.

Name Type Description
instructionGroups

Groups a sequence of instruction elements which are related to each other.

instructions

A list of instructions describing maneuvers.

RouteResultInstruction

A set of attributes describing a maneuver, e.g. 'Turn right', 'Keep left', 'Take the ferry', 'Take the motorway', 'Arrive'.

Name Type Description
countryCode
  • string

3-character ISO 3166-1 alpha-3 country code. E.g. USA.

drivingSide

Indicates left-hand vs. right-hand side driving at the point of the maneuver.

instructionType

Type of the instruction, e.g., turn or change of road form.

maneuver

A code identifying the maneuver.

message
  • string

A human-readable message for the maneuver.

point

A location represented as a latitude and longitude.

possibleCombineWithNext
  • boolean

It is possible to optionally combine the instruction with the next one. This can be used to build messages like "Turn left and then turn right".

routeOffsetInMeters
  • integer

Distance from the start of the route to the point of the instruction.

street
  • string

Street name of the next significant road segment after the maneuver, or of the street that should be followed.

travelTimeInSeconds
  • integer

Estimated travel time up to the point corresponding to routeOffsetInMeters.

RouteResultInstructionGroup

Groups a sequence of instruction elements which are related to each other. The sequence range is constrained with firstInstructionIndex and lastInstructionIndex. When human-readable text messages are requested for guidance (instructionType=text or tagged), then the instructionGroup has a summary message returned when available.

Name Type Description
firstInstructionIndex
  • integer

Index of the first instruction.

groupLengthInMeters
  • integer

Length of the group.

groupMessage
  • string

Summary message when human-readable text messages are requested for guidance (instructionType=text or tagged).

lastInstructionIndex
  • integer

Index of the last instruction.

RouteResultLeg

Name Type Description
points

Points array

summary

Summary object for route section.

RouteResultLegSummary

Summary object for route section.

Name Type Description
arrivalTime
  • string

Arrival Time property

batteryConsumptionInkWh
  • number

Estimated electric energy consumption in kilowatt hours (kWh) using the Electric Consumption Model. Included if vehicleEngineType is set to electric and constantSpeedConsumptionInkWhPerHundredkm is specified. The value of batteryConsumptionInkWh includes the recuperated electric energy and can therefore be negative (which indicates gaining energy). If both maxChargeInkWh and currentChargeInkWh are specified, recuperation will be capped to ensure that the battery charge level never exceeds maxChargeInkWh. If neither maxChargeInkWh nor currentChargeInkWh are specified, unconstrained recuperation is assumed in the consumption calculation.

departureTime
  • string

Departure Time property

fuelConsumptionInLiters
  • number

Estimated fuel consumption in liters using the Combustion Consumption Model. Included if vehicleEngineType is set to combustion and constantSpeedConsumptionInLitersPerHundredkm is specified. The value will be non-negative.

historicTrafficTravelTimeInSeconds
  • integer

Estimated travel time calculated using time-dependent historic traffic data. Included only if computeTravelTimeFor = all is used in the query.

lengthInMeters
  • integer

Length In Meters property

liveTrafficIncidentsTravelTimeInSeconds
  • integer

Estimated travel time calculated using real-time speed data. Included only if computeTravelTimeFor = all is used in the query.

noTrafficTravelTimeInSeconds
  • integer

Estimated travel time calculated as if there are no delays on the route due to traffic conditions (e.g. congestion). Included only if computeTravelTimeFor = all is used in the query.

trafficDelayInSeconds
  • integer

Traffic Delay In Seconds property

travelTimeInSeconds
  • integer

Estimated travel Time In Seconds property

RouteResultSection

Name Type Description
delayInSeconds
  • integer

Delay in seconds caused by the incident.

effectiveSpeedInKmh
  • integer

Effective speed of the incident in km/h, averaged over its entire length.

endPointIndex
  • integer

End Point Index property

magnitudeOfDelay

The magnitude of delay caused by the incident. These values correspond to the values of the response field of the Get Traffic Incident Detail API.

sectionType
  • string

Section Type property

simpleCategory
  • string

Type of the incident. Can currently be JAM, ROAD_WORK, ROAD_CLOSURE, or OTHER. See "tec" for detailed information.

startPointIndex
  • integer

Start Point Index property

tec

Details of the traffic event, using definitions in the TPEG2-TEC standard. Can contain and elements.

travelMode
  • string

Travel Mode property

RouteResultSectionTec

Details of the traffic event, using definitions in the TPEG2-TEC standard. Can contain and elements.

Name Type Description
causes

List of elements.

effectCode
  • integer

The effect on the traffic flow. Contains a value in the tec001:EffectCode table, as defined in the TPEG2-TEC standard. Can be used to color-code traffic events according to severity.

RouteResultSectionTecCause

The cause of the traffic event. Can contain and elements. Can be used to define iconography and descriptions.

Name Type Description
mainCauseCode
  • integer

The main cause of the traffic event. Contains a value in the tec002:CauseCode table, as defined in the TPEG2-TEC standard.

subCauseCode
  • integer

The subcause of the traffic event. Contains a value in the sub cause table defined by the mainCauseCode, as defined in the TPEG2-TEC standard.

RouteType

The type of route requested.

Name Type Description
eco
  • string

A route balanced by economy and speed.

fastest
  • string

The fastest route.

shortest
  • string

The shortest route by distance.

thrilling
  • string

Includes interesting or challenging roads and uses as few motorways as possible. You can choose the level of turns included and also the degree of hilliness. See the hilliness and windingness parameters for how to set this. There is a limit of 900 km on routes planned with routeType=thrilling

SectionType

Specifies which of the section types is reported in the route response.

For example if sectionType = pedestrian the sections which are suited for pedestrians only are returned. Multiple types can be used. The default sectionType refers to the travelMode input. By default travelMode is set to car

Name Type Description
carTrain
  • string

Get sections if the route includes car trains.

country
  • string

Countries the route has parts in.

ferry
  • string

Get sections if the route includes ferries.

motorway
  • string

Get sections if the route includes motorways.

pedestrian
  • string

Get sections which are suited for pedestrians.

tollRoad
  • string

Get sections which require a toll to be payed.

tollVignette
  • string

Get sections which require a toll vignette to be present.

traffic
  • string

Get sections which contain traffic information.

travelMode
  • string

Get sections in relation to the request parameter travelMode.

tunnel
  • string

Get sections if the route includes tunnels.

TextFormat

Desired format of the response. Value can be either json or xml.

Name Type Description
json
  • string

The JavaScript Object Notation Data Interchange Format

xml
  • string

The Extensible Markup Language

TravelMode

The mode of travel for the requested route. Note that the requested travelMode may not be available for the entire route. Where the requested travelMode is not available for a particular section, the travelMode element of the response for that section will be other. Note that travel modes bus, motorcycle, taxi and van are BETA functionality. Full restriction data is not available in all areas. In calculateReachableRange requests, the values bicycle and pedestrian must not be used

Name Type Description
bicycle
  • string

bicycle

bus
  • string

bus

car
  • string

car

motorcycle
  • string

motorcycle

pedestrian
  • string

pedestrian

taxi
  • string

taxi

truck
  • string

truck

van
  • string

van

VehicleEngineType

Engine type of the vehicle. When a detailed Consumption Model is specified, it must be consistent with the value of vehicleEngineType.

Name Type Description
combustion
  • string

Internal combustion engine.

electric
  • string

Electric engine.

VehicleLoadType

Types of cargo that may be classified as hazardous materials and restricted from some roads. Available vehicleLoadType values are US Hazmat classes 1 through 9, plus generic classifications for use in other countries. Values beginning with USHazmat are for US routing while otherHazmat should be used for all other countries. vehicleLoadType can be specified multiple times. This parameter is currently only considered for travelMode=truck.

Name Type Description
USHazmatClass1
  • string

Explosives

USHazmatClass2
  • string

Compressed gas

USHazmatClass3
  • string

Flammable liquids

USHazmatClass4
  • string

Flammable solids

USHazmatClass5
  • string

Oxidizers

USHazmatClass6
  • string

Poisons

USHazmatClass7
  • string

Radioactive

USHazmatClass8
  • string

Corrosives

USHazmatClass9
  • string

Miscellaneous

otherHazmatExplosive
  • string

Explosives

otherHazmatGeneral
  • string

Miscellaneous

otherHazmatHarmfulToWater
  • string

Harmful to water

Windingness

Level of turns for thrilling route. This parameter can only be used in conjunction with routeType=thrilling.

Name Type Description
high
  • string

high

low
  • string

low

normal
  • string

normal