Snap Points to Roads

The Bing Maps Snap to Road API takes GPS point data, in the form of latitudes and longitudes, and returns a list of objects that form a route snapped to the roads on a map. The information returned on the road segments, include the names of the roads that the GPS points are associated with and their posted speed limits. You can also interpolate the GPS points, resulting in a route that smoothly follows the geometry of the road for map display purposes, which is a valuable feature when tracking assets and for data visualization.

When you make a request by using one of the following URL templates, the response returns a SnapToRoadResponse resource that contains the requested snapped coordinate information. For more information about the SnapToRoadResponse resource, see Snap to Road Data. You can also view the example URL and response values in the Examples section.

The algorithm that powers the Bing Maps Snap to Road API is based on this great paper written by Microsoft Research.

For Snap Points to Roads geographic availability, see the travelMode parameter below.

API Limits

Requests to the Snap to Road API can be done in one of two ways:

• Synchronous requests can be made with up to 100 points.
• Asynchronous requests can be made with up to 1,000 points. It is recommended to make this request using POST when passing in more than 100 points.

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 has less than a hundred points.

URL Template

Synchronous GET Requests

When making a GET request the URL should look something like this:

http://dev.virtualearth.net/REST/v1/Routes/SnapToRoad?points={points}&interpolate={interpolate}&includeSpeedLimit={includeSpeedLimit}&includeTruckSpeedLimit={includeTruckSpeedLimit}&speedUnit={speedUnit}&travelMode={travelMode}&key={BingMapsKey}

URI parameter alias’s will be supported only for GET requests.

Synchronous POST requests

HTTP POST Request URL

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

POST Header

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

POST body

{
    "points": [{
        "latitude": number,
        "longitude": number
    }],
    "interpolate": bool,
    "includeSpeedLimit": bool,
    "includeTruckSpeedLimit": bool,
    "speedUnit": string,
    "travelMode": string
}

Asynchronous GET Request URL

https://dev.virtualearth.net/REST/v1/Routes/SnapToRoadAsync?points={points}&interpolate={interpolate}&includeSpeedLimit={includeSpeedLimit}&includeTruckSpeedLimit={includeTruckSpeedLimit}&speedUnit={speedUnit}&travelMode={travelMode}&key={BingMapsKey}

Asynchronous POST Request URL

HTTP POST Request URL

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

POST Header

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

POST body

{
    "points": [{
        "latitude": number,
        "longitude": number
    }],
    "interpolate": bool,
    "includeSpeedLimit": bool,
    "includeTruckSpeedLimit": bool,
    "speedUnit": string,
    "travelMode": 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 SnapToRoadAsyncCallback 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/SnapToRoadAsyncCallback?requestId={requestId}&key={BingMapsKey}

Template Parameters

The following is a list of parameters that are supported by the Snap to Road API.

Template POST body with vehicle attributes

{
    "points": [{
        "latitude": number,
        "longitude": number
    }],
    "interpolate": bool,
    "includeSpeedLimit": bool,
    "includeTruckSpeedLimit": bool,
    "speedUnit": string,
    "travelMode": string,
    "vehicleSpec": {
        "dimensionUnit": string,
        "weightUnit": string,
        "vehicleHeight": number,
        "vehicleWidth": number,
        "vehicleLength": number,
        "vehicleWeight": number,
        "vehicleAxles": number,
        "vehicleTrailers": number,
        "vehicleSemi": bool,
        "vehicleMaxGradient": number,
        "vehicleMinTurnRadius": number,
        "vehicleAvoidCrossWind": bool,
        "vehicleAvoidGroundingRisk": bool,
        "vehicleHazardousMaterials": string,
        "vehicleHazardousPermits": string
    }
}

Examples

Snap points to road

The following example shows how to snap points to the road.

In this case, consider a trucking company that wants to do periodic safety reviews of the routes that their truck drivers take. The trucks have built-in GPS devices that collect GPS points as the truck drives along its route. The company wants to snap the GPS points to the likely road taken for accuracy because often times collected GPS points can deviate from the actual road the driver was on due to occasional GPS signal interference (i.e.: trees, buildings, etc.). The company also wants to get the posted truck speed limit of the road that the truck was on to compare to the actual speed the driver was travelling.

HTTP GET Request URL

https://dev.virtualearth.net/REST/v1/Routes/SnapToRoad?points=47.590868,-122.336729;47.601604,-122.336042;47.60849,-122.34241;47.610568,-122.345064&includeTruckSpeedLimit=true&IncludeSpeedLimit=true&speedUnit=MPH&travelMode=driving&key={BingMapsKey}

HTTP POST Request URL

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

HTTP POST Header

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

HTTP POST Body

{
    "points":  [
        { "latitude": 47.590868, "longitude": -122.336729 },
        { "latitude": 47.601604, "longitude": -122.336042 },
        { "latitude": 47.608490, "longitude": -122.342410 },
        { "latitude": 47.610568, "longitude": -122.345064 }    
    ],
    "includeSpeedLimit": true,
    "includeTruckSpeedLimit": true,
    "speedUnit": "MPH",
    "travelMode": "driving"
}

Below is an example of HTTP POST Body with vehicle spec:

{
    "points":  [
        { "latitude": 47.590868, "longitude": -122.336729 },
        { "latitude": 47.601604, "longitude": -122.336042 },
        { "latitude": 47.608490, "longitude": -122.342410 },
        { "latitude": 47.610568, "longitude": -122.345064 }    
    ],
    "includeSpeedLimit": true,
    "includeTruckSpeedLimit": true,
    "speedUnit": "MPH",
    "travelMode": "driving",
    "vehicleSpec": {
        "vehicleHeight": 10,
        "vehicleWidth": 12,
        "vehicleLength": 20,
        "vehicleWeight": 5000,
        "vehicleAxles": 2,
        "vehicleTrailers": 1
    }
}

Notice that both standard and truck speed limits are requested in this query. The reason for this is few roads have posted truck speed limits, when there is no posted truck speed limit the value returned will be 0. When this occurs, the standard posted speed limit is assumed to also apply to trucks as well.

To view the complete XML and JSON responses, see Snap to Road 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
• Snap to Road Example