Distance Matrix Data
Note
Bing Maps Calculate a Distance Matrix API retirement
Bing Maps Calculate a Distance Matrix API is deprecated and will be retired. Free (Basic) account customers can continue to use Bing Maps Calculate a Distance Matrix API until June 30th, 2025. Enterprise account customers can continue to use Bing Maps Calculate a Distance Matrix API until June 30th, 2028. To avoid service disruptions, all implementations using Bing Maps Calculate a Distance Matrix API will need to be updated to use Azure Maps Route Matrix API by the retirement date that applies to your Bing Maps for Enterprise account type. A new version of the Azure Maps Route Matrix API, with support for larger matrices, will be released soon.
Azure Maps is Microsoft's next-generation maps and geospatial services for developers. Azure Maps has many of the same features as Bing Maps for Enterprise, and more. To get started with Azure Maps, create a free Azure subscription and an Azure Maps account. For more information about azure Maps, see Azure Maps Documentation. For migration guidance, see Bing Maps Migration Overview.
The response returned when making an asynchronous request to the Distance Matrix API contains a DistanceMatrixAsyncStatus resource which provides information on the status of the request.
The response returned when making a synchronous request to the Distance Matrix API contains a DistanceMatrix resource. The information provided in the DistanceMatrix resource includes an array of results which correspond to each origin and destination pair in the request. If the request was made asynchronously, the response would provide a request id which can be used to query the status of the asynchronous request.
The following tables provide the descriptions of the DistanceMatrix and DistanceMatrixAsyncStatus resource fields.
For more information about the common response syntax for the Bing Maps REST Services, see Common Response Description.
DistanceMatrixAsyncStatus Resource
A DistanceMatrixAsyncStatus resource is returned as a response when making a DistanceMatrixAsync request. This resource provides the status of an asynchronous distance matrix request which includes an estimated amount of time left to process the request, the unique requestId to use when checking the status, as well as information on if the request was had any errors or not.
| JSON | XML | Type | Description |
|---|---|---|---|
callbackInSeconds |
CallbackInSeconds |
integer |
An estimated number of seconds remaining to complete the request. Wait this long before checking the status again. |
callbackUrl |
CallbackUrl |
string |
The callback URL to use to check the status of the request. |
isAccepted |
IsAccepted |
boolean |
Specifies if the request is accepted. A request will not be accepted if it is not valid, or is not within the coordinate pair limits. |
isCompleted |
IsCompleted |
boolean |
Specifies is the request has completed. |
requestId |
RequestId |
string |
A unique identifier for an asynchronous request. This can be used to retrieve the results of an asynchronous request when it has completed. |
resultUrl |
ResultUrl |
string |
When completed, this field will be populated with a URL which can be used to download the results. The downloaded results will be a DistanceMatrix resource in JSON format. |
DistanceMatrix Resource
The following tables describe the fields in the DistanceMatrix resource in a hierarchical manner.
A distance matrix has the following basic structure:
- DistanceMatrix [one]
- DistanceMatrixCell [For each origin-destination pair and time interval]
Top-level Distance Matrix Resource Fields
The following fields are the top-level fields in the DistanceMatrix resource. Additional tables describe the fields in each cell of array of results.
| JSON | XML | Type | Description |
|---|---|---|---|
destinations |
Destinations |
Coordinate[] |
The array of destinations that were used to calculate the distance matrix. |
origins |
Origins |
Coordinate[] |
The array of destinations that were used to calculate the distance matrix. |
result |
Result |
DistanceMatrixCell[] |
Array of distance matrix cell results containing information for each coordinate pair and time interval. |
Distance Matrix Cell Fields
These fields are specific to the array of DistanceMatrixCells in the DistanceMatrix resource.
| JSON | XML | Type | Description |
|---|---|---|---|
departureTime |
DepartureTime |
string |
The departure time in which this cell was calculated for. Only returned when a startTime is specified. When an endTime is specified in the request several cells will be returned for the same origin and destination pairs, each having a different departure time for each time interval in the generated histogram request. This string is in ISO 8601 date format.Example: 2017-09-22T19:27:03.0000000+00:00 |
destinationIndex |
DestinationIndex |
int |
The index of the destination in the provided destinations array used to calculate this cell. |
hasError |
HasError |
boolean |
A boolean indicating if an error occurred when calculating this cell. |
originIndex |
OriginIndex |
int |
The index of the origin in the provided origins array used to calculate this cell. |
travelDistance |
TravelDistance |
double |
The physical distance covered to complete a route between the origin and destination. Currently all distances returned are in kilometers. When travel mode is set to transit or a path between the origin and destination can't be calculated, this value is set to -1. |
travelDuration |
TravelDuration |
double |
The time that it takes, in the specified time units, to travel a corresponding TravelDistance. If a path a path between the origin and destination can't be calculated, this value will be a negative number. |
totalWalkDuration |
TotalWalkDuration |
double |
The portion of the total route duration which requires walking. This may occur when the travel mode is set to transit. |
Coordinate Field
These fields are used to represent a location coordinate.
| JSON | XML | Type | Description |
|---|---|---|---|
latitude |
Latitude |
double |
The latitude information of the coordinate. |
longitude |
Longitude |
double |
The longitude information of the coordinate. |