Drive Time and Direction API
Use this API to get drive time and direction information for specific locations based on the configured default map provider.
API Definition
This API is defined in the MapProviderManager class.
public static ResultObject retrieveDirectionInfo(IGeography sourceLocation, IGeography destLocation, DateTime departureTime, DateTime arrivalTime)
Parameters
|
Name
|
Required?
|
Description
|
|---|---|---|
|
sourceLocation
|
Yes
|
Starting location for the drive.
|
|
destLocation
|
Yes
|
Destination location for the drive.
|
|
departureTime
|
No
|
Desired departure time. Times cannot be in the past.
|
|
arrivalTime
|
No
|
Desired arrival time.
|
 |
At this time, departureTime and arrivalTime are supported only for Google Maps and OSM/MapBox. You can specify either of these parameters, but you cannot use both at the same time.
|
Response Attributes
The return type is resultObject, which defines the information that is included in this API’s response.
|
Name
|
Description
|
|---|---|
|
status_code
|
Status code of the API response. For more information, see Drive Time API Response Status Codes below.
|
|
status_message
|
Status message of the API response.
|
|
direction_info
|
Direction information in JSON format.
|
|
total_duration
|
Total drive time duration from starting to destination locations, in minutes.
|
|
total_distance
|
Total distance between starting and destination locations, in meters.
|
Response Example
{
"status_code": 0,
"status_message": "Success",
"direction_info": {
"total_duration": "23",
"total_distance": "11543.6"
}
}
"status_code": 0,
"status_message": "Success",
"direction_info": {
"total_duration": "23",
"total_distance": "11543.6"
}
}
Drive Time API Response Status Codes
|
Code
|
Message
|
Description
|
|---|---|---|
|
0
|
Success
|
Request successful. Drive time and direction information returned.
|
|
1
|
Request success but no result return.
|
Request successful. No route or road segments found for specified location, therefore no results returned.
|
|
2
|
Request success with multiple results return.
|
Request successful. Multiple results returned.
|
|
3
|
Invalid request
|
Missing sourceLocation or destLocation parameters, or departuretTime and arrivalTime parameters specified together.
|
|
4
|
No default map provider specified in current setting.
|
No default map provider configured in the active system setting.
|
|
5
|
Invalid API Key.
|
Specified API key is invalid.
|
|
6
|
Invalid signature or client id.
|
Specified signature value is invalid for the specified client ID, or the specified client value is invalid.
|
|
7
|
Request over query limit.
|
Request exceeds the query quota.
|
|
8
|
Unable to authenticate the request.
|
Unsuccessful request caused by a map provider server authentication issue.
|
|
9
|
Current map provider is not supported.
|
Current map provider not supported for the Drive Time and Direction API. At this time, only Google and OpenStreetMap are supported.
|
|
11
|
Failed to encode location.
|
Failed to encode geographic location.
|
|
13
|
The requested route is too long and cannot be processed.
|
The distance between the starting location and destination exceeds the maximum route value that can be calculated.
|
|
101
|
Server Internal Error.
|
Server internal errors occurred on the map provider server.
|
|
102
|
Unknown error.
|
Other unknown errors returned from the map provider server.
|
Example
import import com.servicemax.mapproviders.MapProviderManager
import com.intalio.com.data.geography.Geography
import com.intalio.core.data.api.IGeography
import org.joda.time.DateTime
IGeography source = new Geography("37.3893889","-122.0832101")
IGeography destination = new Geography("38.3893889","-122.0832101")
DateTime departureTime = new DateTime('2020-11-12T08:00:00.000Z')
def res = MapProviderManager.retrieveDirectionInfo(source, destination, departureTime, null);
import com.intalio.com.data.geography.Geography
import com.intalio.core.data.api.IGeography
import org.joda.time.DateTime
IGeography source = new Geography("37.3893889","-122.0832101")
IGeography destination = new Geography("38.3893889","-122.0832101")
DateTime departureTime = new DateTime('2020-11-12T08:00:00.000Z')
def res = MapProviderManager.retrieveDirectionInfo(source, destination, departureTime, null);
Map Provider Considerations
The Google Maps API (https://developers.google.com/maps/documentation/directions/intro) uses traffic conditions data for arrival time calculations only when you specify departureTime while you use this API. If you set only arrivalTime, traffic conditions data is not used. If neither parameter is set, departureTime is set as Now by default.
For OSM, you must specify a MapBox access token, because this API is implemented by the MapBox Direction Service. OSM uses the specified departureTime and arrivalTime values for travel time calculation. In cases where departureTime and arrivalTime values are not specified, current traffic conditions data is used. For the MapBox Directions API, see https://www.mapbox.com/api-documentation/#directions. For a list of geographies that support traffic conditions data, see https://www.mapbox.com/api-documentation/pages/traffic-countries.html.
For more information: