Calculate an Isochrone

The Bing Maps Isochrone API provides time-specific, isoline polygons for the distance that is reachable from a given location and supports multiple modes of transportation (i.e. driving and public transit). Use this solution to plan the area that can be reached from a designated starting point within a set time period. The isoline polygon area, good for visualization, can be used to filter for spatial queries, which opens up a wide variety of applications for spatial filtering. Here are some additional examples of where you might use isochrones:

• Store Locators – Show me all locations that are within 10 minutes of a user.
• Stolen Vehicle Recovery – Where could a vehicle have travelled to since it was stolen.
• Real Estate – Limit search results such that only those that are within the users preferred commute preferences to work. For example, show me all homes that are within a 30-minute drive of work.
• Job Search Sites – Show all jobs that are within 45 minutes of my home when taking public transit.
• Geofence Generation – Generate a polygon that be used as a geofence that alerts users when they are within a certain travel time or distance of a location.
• Field management – Show me all workers who are within a 15-minute drive of a job.
• Emergency Services Planning – Where could an emergency vehicle travel too within 5, 10, and 15 minutes.

When you make a request by using one of the following URL templates, the response returns either a IsochroneResponse resource that contains the requested isochrone information or an RouteProxyAsyncResult resource which contains information on the asynchronous request that was made to calculate an isochrone. For more information about these resources, see Isochrone Data. You can also view the example URL and response values in the Examples section.

For Calculate an Isochrone geographic availability, see the travelMode parameter below.

API Limits

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

• Most requests can be made with a simple synchronous GET request. Recommended for shorter travel times less than 30 minutes and distances less than 15 miles (24 km).
• An asynchronous request can be made for lager isochrones. Larger isochrones take longer to be generated as the network of possible roads grows exponentially.

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

URL Template

Synchronous GET Requests

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

https://dev.virtualearth.net/REST/v1/Routes/Isochrones?waypoint={waypoint}&maxtime={maxTime}&maxDistance={maxDistance}&timeUnit={timeUnit}&distanceUnit={distanceUnit}&dateTime={dateTime}&travelMode={travelMode}&key={BingMapsKey}

Asynchronous GET Requests

Creates a job to calculate an isochrone using an asynchronous GET request. This type of request is recommended when the maxTime parameter is more than 30 minutes or the maxDistance parameter is more than 15 miles (24 km).

http://dev.virtualearth.net/REST/v1/Routes/IsochronesAsync?waypoint={waypoint}&maxtime={maxTime}&maxDistance={maxDistance}&timeUnit={timeUnit}&distanceUnit={distanceUnit}&dateTime={dateTime}&travelMode={travelMode}&key={BingMapsKey}

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 IsochroneAsyncCallback 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/IsochronesAsyncCallback?requestId={requestId}&key={BingMapsKey}

Synchronous POST Requests

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

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

Asynchronous POST Requests

Creates a job to calculate an isochrone using an asynchronous POST request. This type of request is recommended when the maxTime parameter is more than 30 minutes or the maxDistance parameter is more than 15 miles (24 km).

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

Template Parameters

The following is a list of parameters that are supported by the Isochrone API.

¹ transit will no longer be a valid travelMode as of 9/30/2024.

Template POST body with vehicle attributes

{
    "waypoint":string,
    "distanceUnit": string,
    "travelMode": string,
    "optimize": string,
    "maxDistance" : number,
    "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

Calculate an Isochrone (synchronous)

The following example shows how to request an isochrone.

In this case, consider a delivery company that has some electric vehicles in their fleet that have a maximum range of 100 miles on a fully charged battery. The company would like to determine which customer delivery locations the electric vehicles can reach and return back to the shop without having to recharge the vehicle battery. The company can use the resulting isochrone to assign the electric vehicles to only customer deliveries that are within the isochrone polygon.

• maxDistance: 50 miles (100 miles roundtrip)
• distanceUnit: mile
• optimize: distance
• travelMode: driving
• waypoint: Delivery company's shop latitude/longitude

HTTP GET Request URL

https://dev.virtualearth.net/REST/v1/Routes/Isochrones?waypoint=31.520759,-97.133597&maxDistance=50&distanceUnit=mile&optimize=distance&travelMode=driving&key={BingMapsKey}

For isochrones with specific vehicle attributes, below are the example POST request URLs.

URL Template for Synchronous POST request

https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fdev.virtualearth.net%2FREST%2Fv1%2FRoutes%2FIsochrones%3Fkey&data=02%7C01%7Cyasong%40microsoft.com%7C08d8aa10e2be4c1c8a8e08d7825ab785%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637121198441257460&sdata=Dz8aDorHqG7%2FgWFaaJmvEDamsVfP3lcuNAt%2Bf6SP7ug%3D&reserved=0={BingMapsKey}

Asynchronous POST request

https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fdev.virtualearth.net%2FREST%2Fv1%2FRoutes%2FIsochronesAsync%3Fkey&data=02%7C01%7Cyasong%40microsoft.com%7C08d8aa10e2be4c1c8a8e08d7825ab785%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637121198441257460&sdata=8clzM%2Bk0HrDeBjlw2yhMMGQWFg%2FhL7fdmkYSRfge3Vc%3D&reserved=0={BingMapsKey}

Example POST Body with vehicle attributes

{
    "waypoint":"31.520759,-97.133597",
    "distanceUnit": "mile",
    "travelMode": "Truck",
    "optimize": "distance",
    "maxDistance" : 30,
    "vehicleSpec": {
        "vehicleHeight": 10,
        "vehicleWidth": 12,
        "vehicleLength": 20,
        "vehicleWeight": 5000,
        "vehicleAxles": 2,
        "vehicleTrailers": 1
    }
}

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

Calculate an Isochrone (asynchronous)

The following example shows how to request an isochrone asynchronously.

In this case, consider a person that is looking to rent an apartment near their company's office and doesn’t want more than a 30 minute commute by car back home each evening. The resulting isochrone can be used to limit the apartment search to only apartment listings within that commute polygon.

• maxTime: 30 minutes
• TimeUnit: minute
• DateTime: 11/27/2017 (Monday) at 6 PM PST (UTC offset)
• TravelMode: Driving
• Waypoint: Company's office address

HTTP GET Request URL

http://dev.virtualearth.net/REST/v1/Routes/IsochronesAsync?waypoint=1%20Microsoft%20Way%20Redmond%20WA&maxTime=30&timeUnit=minute&dateTime=2017-11-27T18:00:00-08:00&travelMode=Driving&key={BingMapsKey}

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 isochrone 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/IsochroneAsyncCallback?requestId=90b07189-33d8-4cbf-866a-1bd5c5b4f474&key={BingMapsKey}

The following image shows the resulting isochrone.

To view the complete XML and JSON responses, see Isochrone 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
• Isochrone Data
• Isochrone Example
• Isochrone Asynchronous Example