Calculate a Truck Route

The Bing Maps Truck Routing API provides travel routes which take truck attributes such as size, weight and type of cargo. This is important as not all trucks can travel the same routes as other vehicles. Here are some examples:

• Bridges have heights and weight limits.
• Tunnels often have restrictions on flammable or hazardous materials.
• Longer trucks have difficulty making tight turns.
• Highways often have a separate speed limit for trucks.
• Certain trucks may want to avoid roads that have steep gradients.

The Bing Maps Truck Routing API is an extension of the existing Bing Maps Routing API and supports many of the same request parameters, and responds with the same Route resource class. Note that each request to the Truck Routing API generates three (3) billable transactions.

When you make a request by using one of the following URL templates, the response returns either a Route resource that contains the truck based routing information or RouteProxyAsyncResult resource which contains information on the asynchronous request that was made to calculate a truck route. For more information about the Route resource, see Route Data. You can also view the example URL and response values in the Examples section.

Truck routing is only available in certain countries/regions, see the Coverage documentation for details.

API Limits

Requests to the Truck Routing API can be done in one of two ways:

• Most requests can be made with a simple synchronous GET or POST request. Recommended for shorter routes within a single city or state.
• Longer routes which take longer to process, such as multiple state or cross-country routes can be made by making an asynchronous Truck routing request.

If you are not sure which one to use, it is recommended to use the asynchronous method as this will work for all scenarios.

How asynchronous requests work

See Asynchronous Requests documentation.

Supported HTTP Methods

GET, POST

POST requests require all parameters to be passed into the body of the request as a JSON object. This API is CORs enabled.

When to use HTTP GET vs POST

Many developers prefer the simplicity of HTTP GET requests which simply require generating a URL. However, browsers and servers have limits on the maximum length that URLs can be. Typically, it is best to keep your URLs under 2083 characters in length. With this in mind, it is recommended to only use HTTP GET requests when your request is between a few waypoints and only some of the truck attributes options are specified.

URL Template

Truck route calculations require a lot more processing than standard driving route calculations, as such synchronous and asynchronous requests are supported. It is recommended to use the asynchronous request when calculating longer routes.

There are a lot of options available for truck routes. As such, some requests could result in long URL’s which may exceed browser limits. As such requests can be made using GET and POST. CORs is enabled to allow cross platform POST requests.

Synchronous Truck Routing Request URL (GET)

https://dev.virtualearth.net/REST/v1/Routes/Truck?wayPoint.1={wayPpoint1}&viaWaypoint.2={viaWaypoint2}&waypoint.3={waypoint3}&wayPoint.n={waypointN}&heading={heading}&optimize={optimize}&avoid={avoid}&distanceBeforeFirstTurn={distanceBeforeFirstTurn}&routeAttributes={routeAttributes}&dateTime={dateTime}&tolerances={tolerances}&distanceUnit={distanceUnit}&vehicleHeight={vehicleHeight}&vehicleWidth={vehicleWidth}&vehicleLength={vehicleLength}&vehicleWeight={vehicleWeight}&vehicleAxles={vehicleAxles}&vehicleTrailers={vehicleTrailers}&vehicleSemi={vehicleSemi}&vehicleMaxGradient={vehicleMaxGradient}&vehicleMinTurnRadius={vehicleMinTurnRadius}&vehicleHazardousMaterials={vehicleHazardousMaterials}&vehicleHazardousPermits={vehicleHazardousPermits}&key={BingMapsKey}

Synchronous Truck Routing Request URL (POST)

HTTP POST Request URL

https://dev.virtualearth.net/REST/v1/Routes/Truck?key={BingMapsKey}

POST Header

Content-Length: insertLengthOfHTTPBody
Content-Type: application/json

POST body

{
    "waypoints": [{
        "address": string,
        "latitude": number,
         "longitude": number,
        "isViaPoint": bool
    },
    …],
    "avoid": string,
    "dateTime": string,
    "distanceBeforeFirstTurn": number,
    "distanceUnit": string,
    "heading": number,
    "optimize": string,
    "routeAttributes": string,
    "tolerances": number[], 
    "vehicleSpec": {
        "dimensionUnit": string,
        "weightUnit": string,
        "vehicleHeight": number,
        "vehicleWidth": number,
        "vehicleLength": number,
        "vehicleWeight": number,
        "vehicleAxles": number,
        "vehicleTrailers": number,
        "vehicleSemi": bool,
        "vehicleMaxGradient": number,
        "vehicleMinTurnRadius": number,
        "vehicleHazardousMaterials": string,
        "vehicleHazardousPermits": string
    }
}

Asynchronous Truck Routing Request URL (GET)

https://dev.virtualearth.net/REST/v1/Routes/TruckAsync?wayPoint.1={wayPpoint1}&viaWaypoint.2={viaWaypoint2}&waypoint.3={waypoint3}&wayPoint.n={waypointN}&heading={heading}&optimize={optimize}&avoid={avoid}&distanceBeforeFirstTurn={distanceBeforeFirstTurn}&routeAttributes={routeAttributes}&dateTime={dateTime}&tolerances={tolerances}&distanceUnit={distanceUnit}&vehicleHeight={vehicleHeight}&vehicleWidth={vehicleWidth}&vehicleLength={vehicleLength}&vehicleWeight={vehicleWeight}&vehicleAxles={vehicleAxles}&vehicleTrailers={vehicleTrailers}&vehicleSemi={vehicleSemi}&vehicleMaxGradient={vehicleMaxGradient}&vehicleMinTurnRadius={vehicleMinTurnRadius}&vehicleHazardousMaterials={vehicleHazardousMaterials}&vehicleHazardousPermits={vehicleHazardousPermits}&key={BingMapsKey}

Synchronous Truck Routing Request URL (POST)

HTTP POST Request URL

https://dev.virtualearth.net/REST/v1/Routes/TruckAsync?key={BingMapsKey}

POST Header

Content-Length: insertLengthOfHTTPBody
Content-Type: application/json

POST body

{
    "waypoints": [{
        "address": string,
        "latitude": number,
         "longitude": number,
        "isViaPoint": bool
    },
    …],
    "avoid": string,
    "dateTime": string,
    "distanceBeforeFirstTurn": number,
    "distanceUnit": string,
    "heading": number,
    "optimize": string,
    "routeAttributes": string,
    "tolerances": number[], 
    "vehicleSpec": {
        "dimensionUnit": string,
        "weightUnit": string,
        "vehicleHeight": number,
        "vehicleWidth": number,
        "vehicleLength": number,
        "vehicleWeight": number,
        "vehicleAxles": number,
        "vehicleTrailers": number,
        "vehicleSemi": bool,
        "vehicleMaxGradient": number,
        "vehicleMinTurnRadius": number,
        "vehicleHazardousMaterials": string,
        "vehicleHazardousPermits": string
    }
}

URL for checking Asynchronous request status (GET)

The initial asynchronous response includes a callbackUrl property which contains the URL that can be used to check the status of the job. Alternatively, the callback URL can also be generated by appending the requestId that is returned in the initial asynchronous request along with the same Bing Maps key used, with the TruckAsyncCallback endpoint as shown below. The response from this request will indicate if the request is complete or not, if complete it will provide a resultUrl property which is a URL that can be used to download the results.

https://dev.virtualearth.net/REST/v1/Routes/TruckAsyncCallback?requestId={requestId}&key={BingMapsKey}

Template Parameters

Hazardous Materials Restrictions

These restrictions apply to truck cargo, where the resulting route excludes roads on which hazardous materials are prohibited from being transported. The rules for excluding roads with such restrictions include:

• when the truck contains hazardous materials, roads prohibited for shipment of dangerous materials are always excluded from route calculation.
• when the request specifies vehicleHazardousMaterials=GoodsHarmfulToWater, roads prohibited for shipment of water pollutants are excluded from route calculation.
• when the request specifies vehicleHazardousMaterials=Explosive,Flammable, roads prohibited for shipment of explosive and flammable materials are excluded from route calculation.
• when the request specifies a hazardous material that is in the truck, roads prohibited for shipment of that specific hazardous material are excluded from the route calculation.

Although some hazardous material categories overlap, the routing engine does not implicitly map the hazardous materials to restricted goods. For example, if the request specifies combustible materials or gas (which could be flammable), roads prohibited for flammable materials are not excluded from the route calculations.

Trailer Restrictions

The Routing API can distinguish between trailer and semi-trailer restrictions. The rules for excluding roads with trailer restrictions are as follows:

• if vehicleTrailers > 0 – roads prohibited for trucks with trailers are excluded from route calculation.
• if vehicleSemi=true and vehicleTrailers > 0 – roads prohibited for trucks with semi-trailers are excluded from route calculation.

Examples

The following example shows how to request a truck route. In this case, consider a truck that may be transporting a flammable material between Pittsburgh Brashear High School (590 Crane Ave, Pittsburgh, PA) and Duquesne University (600 Forbes Ave, Pittsburgh, PA). For comparison, the following image shows the calculated truck route in green and the route a vehicle not carrying flammable material would typically take in red. The primary reason for the difference in routes in this case is that flammable and explosive materials are prohibited inside the Liberty Tunnel. As a result, the route for this truck is 3.9 miles while the route a vehicle that isn’t carrying flammable or explosive material is only 3.1 miles.

All examples include a GET and its equivalent POST.

Calculate a truck based route (synchronous)

The following shows how to synchronously calculate the truck route.

HTTP GET Request URL

https://dev.virtualearth.net/REST/v1/Routes/Truck?wp.0=590%20Crane%20Ave%2C%20Pittsburgh%2C%20PA&wp.1=600%20Forbes%20Ave%2C%20Pittsburgh%2C%20PA&vehicleHazardousMaterials=Flammable&key={BingMapsKey}

HTTP POST Request URL

https://dev.virtualearth.net/REST/v1/Routes/Truck?key={BingMapsKey}

HTTP POST Header

Content-Length: 227                             
Content-Type: application/json

HTTP POST Body

{
    "waypoints": [{
        "address": "590 Crane Ave, Pittsburgh, PA"
    },{
        "address": "600 Forbes Ave, Pittsburgh, PA"
    }],
    "vehicleSpec": {
        "vehicleHazardousMaterials": "Flammable"
    }
}

For comparison the following image shows this truck route in green and a vehicle not carrying flammable material would typically take in red. The primary reason for the difference in routes in this case is that flammable and explosive materials are prohibited inside the Liberty Tunnel. As a result, the route for this truck is 3.9 miles while the route a vehicle that isn’t carrying flammable or explosive material is only 3.1 miles.

To view the complete XML and JSON responses, see Truck Route Example.

Calculate a truck based route (asynchronous)

The following shows how to asynchronously calculate the truck route.

HTTP GET Request URL

https://dev.virtualearth.net/REST/v1/Routes/TruckAsync?wp.0=590%20Crane%20Ave%2C%20Pittsburgh%2C%20PA&wp.1=600%20Forbes%20Ave%2C%20Pittsburgh%2C%20PA&vehicleHazardousMaterials=Flammable&key={BingMapsKey}

HTTP POST Request URL

https://dev.virtualearth.net/REST/v1/Routes/TruckAsync?key={BingMapsKey}

HTTP POST Header

Content-Length: 227                             
Content-Type: application/json

HTTP POST Body

{
    "waypoints": [{
        "address": "590 Crane Ave, Pittsburgh, PA"
    },{
        "address": "600 Forbes Ave, Pittsburgh, PA"
    }],
    "vehicleSpec": {
        "vehicleHazardousMaterials": "Flammable"
    }
}

Once the initial request is made a requestId will be returned. A requestId is a unique identifier for the asynchronous request. This can be used to monitor the status of the request until it is completed, at which point the response will include a resultURl property which the resulting truck route can be downloaded from. The following URL checks that status of an asynchronous request that has a requestId of "90b07189-33d8-4cbf-866a-1bd5c5b4f474".

https://dev.virtualearth.net/REST/v1/Routes/TruckAsyncCallback?requestId=90b07189-33d8-4cbf-866a-1bd5c5b4f474&key={BingMapsKey}

To view the complete XML and JSON responses, see Truck Route Asynchronous Example.

HTTP Status Codes

When the request is successful, the following HTTP status code is returned.

• 200

When the request is not successful, the response returns one of the following errors.

• 400
• 401
• 404
• 429
• 500
• 503

See Also

• Using the REST Services with .NET
• Truck Route Example
• Truck Route Asynchronous Example
• Find an Optimized Route with Multiple Waypoints Example