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, walking, 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.
- Recreation – Where could I walk to within 30 minutes of where I am.
- 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.
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
Supported HTTP Methods
These templates support both HTTP and HTTPS protocols. To use this API, you must have a Getting a Bing Maps Key.
Synchronous GET Requests
When making a GET request the URL should look something like this:
Asynchronous GET Request
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).
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.
The following is a list of parameters that are supported by the Isochrone API.
Additional parameters, such as output and JSON callback parameters, are found in Output Parameters.
An alias can be used for a URL parameter when making a GET request to shorten the length of the query parameter. For example, waypoint=47.610,-122.107 can be shortened to wp=47.610,-122.107.
||Required. The point around which the isochrone will be calculated. This can be specified as a Point or address. For more information about Point values, see Location and Area Types.
||Required. The maximum travel time in the specified time units in which the isochrone polygon is generated. Cannot be set when maxDistance is set. Maximum value is 60 minutes when using asynchronous requests.
||Optional. The units in which the maxTime value is specified. One of the following values:
• second [default]
||Required for Driving and Walking. The maximum travel distance in the specified distance units in which the isochrone polygon is generated. Cannot be set when maxTime is set. Distance based isochrones are not supported for transit.
||Optional. The units in which the maxDistance value is specified. One of the following values:
• mile or mi
• kilometer or km [default]
||Optional for time based Driving and Transit. When a maxTime value is specified, predictive traffic data is used to calculate the best isochrone route for the specified date time. This is not supported for distanced based queries.
A string that contains the date and time formatted as a DateTime value. For information about the string representation options for DateTime values, see DateTime.Parse Method (String).
dateTime=05:42:00 [assumes the current day]
dateTime=03/01/2011 [assumes the current time]
||Optional. Specifies what parameters to use to optimize the isochrone route. One of the following values:
• distance: The route is calculated to minimize the distance. Traffic information is not used. Use with maxDistance.
• time [default]: The route is calculated to minimize the time. Traffic information is not used. Use with maxTime.
• timeWithTraffic: The route is calculated to minimize the time and uses current or predictive traffic information depending on if a dateTime value is specified. Use with maxTime.
||Optional. Indicates the which routing profile to snap the points to. Possible values:
• driving [default]
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
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
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”.
The following image shows the resulting isochrone.
To view the complete XML and JSON responses, see Isochrone Asynchronous Example.
HTTP Status Codes
For more details about these HTTP status codes, see Status Codes and Error Handling.
When the request is successful, the following HTTP status code is returned.
When the request is not successful, the response returns one of the following errors.
When making an asynchronous request, if the RouteProxyAsyncResult ErrorMessage says "Timeout occurred", the likely cause is that the maximum time or distance values in the request are too large and is resulting in a timeout on the server when calculating the isochrone.