2. Paths
2.1. Given a list of addresses, find their coordinates. For each address, a list of matches will be eventually returned (asynchronously)
POST /map/v1_3c/geocoding/async
2.1.1. Description
Returns a job identifier which can be used to monitor the job’s progress and retrieve the results
2.1.2. Parameters
| Type | Name | Description | Schema | Default |
|---|---|---|---|---|
Query |
key |
Your API key |
string |
|
Body |
body |
List of addresses to be geocoded |
2.2. Return the result for the given geocoding job
GET /map/v1_3c/geocoding/async/{id}
2.2.2. Parameters
| Type | Name | Description | Schema | Default |
|---|---|---|---|---|
Query |
key |
Your API key |
string |
|
Body |
body |
job identifier |
string |
2.3. Cancel the given geocode job
PUT /map/v1_3c/geocoding/async/{id}/cancel
2.4. Return the progress and status of the given geocoding job
GET /map/v1_3c/geocoding/async/{id}/status
2.4.1. Parameters
| Type | Name | Description | Schema | Default |
|---|---|---|---|---|
Query |
key |
Your API key |
string |
|
Body |
body |
job identifier |
string |
2.5. Geocoding
POST /map/v1_3c/geocoding/sync
2.5.1. Description
Given a list of addresses, find their coordinates. For each address, a list of matches will be returned
2.5.2. Parameters
| Type | Name | Description | Schema | Default |
|---|---|---|---|---|
Query |
key |
Your API key |
string |
|
Body |
body |
List of addresses to be geocoded |
2.6. Map rendering
POST /map/v1_3c/map
2.6.1. Description
Renders a map as a raster image in png format. Annotations such as waypoints are supported. It can be used to produce offline images, and is fast enough to be used interactively. For the best user experience though, client rendering is recommended e.g. with Leaflet or OpenLayers. Please see the examples section to see integration of routing/optimizing with Leaflet
2.6.2. Parameters
| Type | Name | Description | Schema | Default |
|---|---|---|---|---|
Query |
key |
Your API key |
string |
|
Body |
body |
Description of the map to be rendered |
2.7. Optimize the sequence (asynchronously)
POST /map/v1_3c/optimization/async
2.7.1. Description
Returns a job identifier which can be used to monitor the job’s progress and retrieve the results
2.7.2. Parameters
| Type | Name | Description | Schema | Default |
|---|---|---|---|---|
Query |
key |
Your API key |
string |
|
Body |
body |
Description of the distribution problem to be optimized |
2.8. Return the optimization result for the given job
GET /map/v1_3c/optimization/async/{id}
2.8.2. Parameters
| Type | Name | Description | Schema | Default |
|---|---|---|---|---|
Query |
key |
Your API key |
string |
|
Body |
body |
job identifier |
string |
2.9. Cancel the given optimization job
PUT /map/v1_3c/optimization/async/{id}/cancel
2.10. Return the progress and status of the given optimization job
GET /map/v1_3c/optimization/async/{id}/status
2.10.1. Parameters
| Type | Name | Description | Schema | Default |
|---|---|---|---|---|
Query |
key |
Your API key |
string |
|
Body |
body |
job identifier |
string |
2.11. Optimize the sequence (synchronously)
POST /map/v1_3c/optimization/sync
2.11.1. Parameters
| Type | Name | Description | Schema | Default |
|---|---|---|---|---|
Query |
key |
Your API key |
string |
|
Body |
body |
Description of the distribution problem to be optimized |
2.12. Immediately returns true
GET /map/v1_3c/optimization/sync/heartbeat
3. Definitions
3.1. Address
Address fields used for geocoding. For unstructured search, use the freetext field,and for structured search use the corresponding fields (i.e. city, street, etc)
| Name | Description | Schema |
|---|---|---|
city |
Used for structured search |
string |
country |
Used for structured search |
string |
county |
Used for structured search |
string |
freeText |
Freetext address. Using commas to seperate the components yields better results e.g. Flat 2, 12 Arbour Road, Highbury, London N13NW, United Kingdom |
string |
houseNumber |
Used for structured search |
string |
postCode |
Used for structured search |
string |
state |
Used for structured search |
string |
street |
Used for structured search |
string |
suburb |
Used for structured search |
string |
3.2. AddressMatch
A single position returned for geocoding an address
| Name | Description | Schema |
|---|---|---|
airDistanceToRefLocationMeters |
If a refLocation was provided, this field contains the air distance from the refLocation to the address |
number(double) |
areaKm2 |
Area of the address, in square kilometers |
number(double) |
bbox |
Bounding box of the match |
|
coordinates |
Coordinates of the address |
|
distanceToKnownSamePostCodeMeters |
Distance to the nearest known point were the same postcode is used |
number(double) |
internalScore |
The confidence attached to this result. A higher number indicates a higher confidence. |
number(double) |
matchingAddress |
The address found matching the request |
|
routableFromRefLocation |
If a refLocation was provided, this field indicates whether a route could be found between refLocation and the geocoded coordinates |
boolean |
3.3. AddressWithId
Address fields ussed for geocoding + id
| Name | Description | Schema |
|---|---|---|
city |
Used for structured search |
string |
country |
Used for structured search |
string |
county |
Used for structured search |
string |
freeText |
Freetext address. Using commas to seperate the components yields better results e.g. Flat 2, 12 Arbour Road, Highbury, London N13NW, United Kingdom |
string |
houseNumber |
Used for structured search |
string |
id |
arbitrary id of the address |
string |
postCode |
Used for structured search |
string |
state |
Used for structured search |
string |
street |
Used for structured search |
string |
suburb |
Used for structured search |
string |
3.4. Area
An area is defined by the rectangle between 2 coordinates. Note that when an Area is used inside a request the two fields do not need to be actually the top left and bottom right corner, any combination of opposite corners is fine
| Name | Description | Schema |
|---|---|---|
max |
North-East corner’s coordinates |
|
min |
South-West corner’s coordinates |
3.5. BaseResponseStats
Contains meta metrics
| Name | Description | Schema |
|---|---|---|
creditsLeft |
creditsLeft |
number(double) |
info |
information in text format |
string |
3.6. BasicVehicleInfo
Information regarding the vehicle, used to compute the feasability of a given route on the road, but also its time, distance and hence its cost. To retrieve the fastest route, specify a cost per hour of 1 and a cost per km of 0, and vice-versa for the shortest route.
| Name | Description | Schema |
|---|---|---|
avoidTollRoads |
Prevent the vehicle from driving on a toll road. Note that since the toll is applied according to the gross vehicle weight, the field grossWeightTon must also be set to avoid toll roads. Default value is false. |
boolean |
costsPerHour |
Costs of the vehicle , used for driving, loading, unloading, waiting etc. Either the cost per hour or per kilometer must be >0. Default value is 1. |
number(double) |
costsPerKm |
Costs of the vehicle per kilometer. Either the cost per hour or per kilometer must be >0. Default value is 0. |
number(double) |
grossWeightTon |
Gross vehicle weight |
number(double) |
heightMeter |
Height of the vehicle, in meters |
number(double) |
limitToCountryIso |
List of strings representing countries onto which the vehicle is allowed to drive. The country is specified in ISO 3166-2 format (e.g. es for Spain, tr for Turkey, etc). Default is empty, which means all countries are allowed. |
< string > array |
widthMeter |
Width of the vehicle, in meters |
number(double) |
3.7. Coordinates
A point on the Map
| Name | Description | Schema |
|---|---|---|
label |
string |
|
x |
x, aka longitude |
number(double) |
y |
y, aka latitude |
number(double) |
3.8. Depot
| Name | Description | Schema |
|---|---|---|
adminTimeInSeconds |
Administrative time required after the arrival of a vehicle. Specified in seconds |
integer(int32) |
adminTimeOutSeconds |
Administrative time required after loading and before a vehicle leaves the depot. Specified in seconds |
integer(int32) |
location |
Location of the depot |
|
timeWindow |
Opening time of the depot, defining from when vehicles can start and up to when vehicles have to be back. |
3.9. DimensionsCost
| Name | Description | Schema |
|---|---|---|
costsPerOther |
Costs of the vehicle per other |
number(double) |
costsPerVolume |
Costs of the vehicle per volume |
number(double) |
costsPerWeight |
Costs of the vehicle per weight |
number(double) |
3.10. DurationLimitation
| Name | Description | Schema |
|---|---|---|
breakDurationSeconds |
Driving/Usage breaks duration |
integer(int32) |
breakEnabled |
Determines, if driving/usage breaks are enabled |
boolean |
breakPeriodSeconds |
Period of driving/usage breaks |
integer(int32) |
limitSeconds |
Driving/Usage time limit for the vehicle |
integer(int32) |
limited |
Determines, if driving/usage time of the vehicle is limited |
boolean |
3.11. ErrorMessage
| Name | Description | Schema |
|---|---|---|
errorCode |
Error code |
enum (CANNOT_GEOCODE_LOCATION, CANNOT_ROUTE_TO_LOCATION, CANNOT_PLAN_LOCATION, FATAL_OPT_ERROR, FATAL_INTERNAL_ERROR, CANCELLED_BY_USER) |
errorMessage |
Description of the error, in English |
string |
3.12. GeocodingRequest
Request to find coordinates given addresses
| Name | Description | Schema |
|---|---|---|
addresses |
List of addresses |
|
refLocation |
Location of the depot, if specified, a check will be performed to ensure that the geocoded addreses are routable from this point. This is typically the depot’s location |
3.13. GeocodingResponse
Response for a GeocodingRequest
| Name | Description | Schema |
|---|---|---|
addressMatchess |
List of matches per requested address. The matches are in the same order as in the request |
|
bbox |
Bounding box of the whole response, including the refLocation if specified |
|
request |
The geocoding request, with optinally geocoded refLocation |
|
stats |
Stats e.g. time spent, credits left… |
3.15. JobStatus
Information about the progress of a geocoding or optimization job
| Name | Description | Schema |
|---|---|---|
details |
Details regarding the progress |
string |
finalStatus |
final status of the job |
enum (COMPLETED, FAILED) |
jobId |
Job identifier |
string |
progress |
Estimated progress of the job, 0 means not started, 1 is done |
number(double) |
3.16. Load
| Name | Description | Schema |
|---|---|---|
other |
Third dimension of capacity, that can be carried by vehicle |
number(double) |
volume |
Volume that can be carried by vehicle. Specified in arbitrary units (usually palettes or m3).. The same unit must be used when specifying orders' volume |
number(double) |
weight |
Weight that can be carried by vehicle. Specified in arbitrary units (usually kg). The same unit must be used when specifying orders' weight |
number(double) |
3.17. Location
A location either defined by its address or coordinates
| Name | Description | Schema |
|---|---|---|
address |
Address of the location |
|
coordinates |
if not specified, the coordinate will be geocoded based on the address |
3.18. LocationAndOrder
Specifies a pickup/delivery
| Name | Description | Schema |
|---|---|---|
locationInfo |
Information about the customer location |
|
orderId |
external id of the order |
string |
orderInfo |
Information specific to the order picked/delivered |
|
vehicleTypeRestrictions |
List of strings, where each string is a flag representing a vehicle’s capability which is required for this location and/or order (e.g. refrigerator,crane,lifting platform,etc). |
< string > array |
3.19. LocationAndOrderErrorMessage
Describes an error that prevented an order to be planned
| Name | Description | Schema |
|---|---|---|
error |
The reason why the order could not be planned |
|
locationAndOrder |
The order that could not be planned |
3.20. LocationInfo
Information regarding a customer location
| Name | Description | Schema |
|---|---|---|
grossVehicleWeightLimitTons |
Maximum Gross Vehicle Weight authorized for vehicles at this location, in tons |
number(double) |
location |
Address and/or coordinates of the customer |
|
timeWindow1 |
1st time window |
|
timeWindow2 |
2nd time window |
3.21. MapRequest
Request a bitmap image of the map. Either geometry or geometryAroundArea must be defined
| Name | Description | Schema |
|---|---|---|
geometry |
Specifies which area should be displayed on the map, around a given center coordinates |
|
geometryAroundArea |
Specifies which area should be displayed on the map |
|
pois |
List of individual points to be shown as markers on the map. The id field of each point will used as label |
|
traces |
List of traces to be shown on the map |
3.22. MapRequestGeometry
Specifies an exact map geometry
| Name | Description | Schema |
|---|---|---|
center |
Center of the map |
|
viewportHeight |
Height of the returned image |
integer(int32) |
viewportWidth |
Width of the returned image |
integer(int32) |
zoomLevel |
Level of zoom, allowed values range from 3 (largest scale, to display countries/continents) to 18 (lowest scale, to display individual buildings) |
integer(int32) |
3.23. MapRequestGeometryAroundArea
Partially specifies the map geometry, so that the given area fits inside the viewport
| Name | Description | Schema |
|---|---|---|
area |
Area that should be displayed. If not set, the area will be computed based on other elements of the map request , e.g. waypoints |
|
paddingPix |
Minimum padding around the area in pixels (default 30) |
integer(int32) |
viewportHeight |
Height of the returned image |
integer(int32) |
viewportWidth |
Width of the returned image |
integer(int32) |
3.24. MapResponse
Contains a map image, in PNG format
| Name | Description | Schema |
|---|---|---|
area |
The area displayed on the map |
|
fullyLoaded |
Indicates whether the map is fully assembled. If false, some areas might be grayed out or with a lower resolution, and hence the client should display the image, and after a short delay repeat the request |
boolean |
imageBytes |
Png image, encoded in base 64. E.g. to render in javascript, use something like: $('#map').attr('src', 'data:image/png;base64,' + mapResponse.imageBytes). |
string |
stats |
Stats e.g. time spent, credits left… |
|
usedGeometry |
The actual geometry used to display the map (i.e. center coordinates, zoomlevel and viewport size) |
3.25. MatchesForRequestedAddress
Possible coordinates for a given address
| Name | Description | Schema |
|---|---|---|
bbox |
Bounding box of all the matches, if any |
|
matches |
List of matches ordered in decreasing order of confidence |
|
requestedAddress |
Address searched for |
3.26. OrderInfo
| Name | Description | Schema |
|---|---|---|
load |
dimensions of the order to deliver |
|
loadBack |
dimensions of the order to pick |
|
timeAtCustomer |
administrative and (un)loading time at customer, in seconds |
integer(int32) |
3.27. Plan
Contains the plan, i.e. the list of routes that include all orders, if such plan exists. If it is not possible to find a valid plan, a partial plan will be returned
| Name | Description | Schema |
|---|---|---|
bbox |
Bounding box containing all the routes in the plan |
|
expectedTotalCosts |
Estimated costs after the planning of unplanned orders, defined as the cost of planned orders, plus the cost of direct roads for each unplanned order |
number(double) |
expectedTotalKms |
Estimated total distance in km after the planning of unplanned orders, defined as the cost of planned orders, plus the distance of direct roads for each unplanned order |
number(double) |
expectedTotalTimeSeconds |
Estimated total time in seconds after the planning of unplanned orders, defined as the cost of planned orders, plus the time of direct roads for each unplanned order |
integer(int32) |
plannedCosts |
Costs for the delivery of planned orders |
number(double) |
plannedKms |
Total distance in km for the delivery of planned orders |
number(double) |
plannedTimeSeconds |
Total time in seconds for the delivery of planned orders |
integer(int32) |
routes |
List of routes |
|
unplannedOrders |
Number of orders wich could not be planned |
integer(int32) |
3.28. Point2PointRoute
Route to go from one point to another
| Name | Description | Schema |
|---|---|---|
bbox |
Bounding box of the routes |
|
coordinatesPolyline |
string |
|
distanceKm |
Distance of this route, in kms |
number(double) |
found |
Indicates whether a route was found or not |
boolean |
timeSeconds |
Estimation of the duration of this route, in seconds |
integer(int32) |
violationCnt |
Total number of violations on this road |
integer(int32) |
violations |
List of violations on this road. Only populated when the detailedTrace field of the request’s BasicVehicleInfo is true |
3.29. Route
| Name | Description | Schema |
|---|---|---|
bbox |
Bounding box of the route |
|
drivingDistanceMeters |
Driving distance in meters |
integer(int32) |
drivingTimeSeconds |
Driving time in seconds |
integer(int32) |
endTime |
End time, right after unloading and administrative time. In seconds since midnight |
|
legs |
List of legs |
|
load |
Weight of the goods loaded at the depot for this route |
|
loadBack |
Volume of the goods loaded at the depot for this route |
|
minimalGrossVehicleWeightLimitTons |
Minimal Gross Vehicle Weight limit of all visited customer |
number(double) |
startTime |
Start time at the depot; loading of goods starts at this time. In seconds since midnight |
|
stops |
List of stops |
|
vehicle |
Vehicle planned for this route |
|
waitingTimeOnReturnToDepotSeconds |
Waiting time on way back to the depot |
integer(int32) |
3.30. RoutingRequest
Request to compute routes to go from N to M points. Please note that the algorithm is optimized for large matrices, but for a single point to point route it is relatively slow.
| Name | Description | Schema |
|---|---|---|
basicVehicleInfo |
Vehicle properties used to compute the feasability and cost of a given road |
|
detailedTraces |
Indicates that the routes' waypoints should be returned in the response |
boolean |
pointsM |
list of points defining the matrix 1st dimension |
|
pointsN |
list of points defining the matrix 2nd dimension |
3.31. RoutingResponse
List of routes as a response for a RoutingRequest
| Name | Description | Schema |
|---|---|---|
bbox |
Bounding box that contains all routes |
|
routes |
Unidimensional list of routes. Given a request for a M x N matrix, the index of the route m to n corresponds to [m*M+n] ( e.g, the index of the route from m=2 to n=3 is 2*M+3 |
|
stats |
Stats e.g. time spent, credits left… |
3.32. Stop
Describes a stop inside a route. A Stop always corresponds to a delivery/pick up of an order,except for the last stop of the route, which might be included because it was requested explicitely for the vehicle
| Name | Description | Schema |
|---|---|---|
arrivalTime |
Time of arrival at location. In seconds since midnight |
|
departureTime |
Time of departure from location. In seconds since midnight |
|
location |
location of the stop. When the reason is Order, the location is same as in the locationAndOrder |
|
locationAndOrder |
Corresponding order |
|
reason |
Describe the reason for the stop: Depot,Order,Last |
string |
waitingTime |
Waiting time in seconds, before the delivery/pick up can be performed |
integer(int32) |
3.33. TimeOfDay
Local time of day
| Name | Description | Schema |
|---|---|---|
hour |
hour |
integer(int32) |
minutes |
minutes |
integer(int32) |
seconds |
seconds |
integer(int32) |
3.34. TimeWindow
Describes a slot of time when a resource is available. Used for Vehicles, and for Orders (An Order can specify 2 time windows)
| Name | Description | Schema |
|---|---|---|
from |
start of the time window, in seconds since midnight |
|
to |
end of the time window, in seconds since midnight |
3.35. Trace
A list of points to be displayed on the map as a continuous line
| Name | Description | Schema |
|---|---|---|
color |
Color of the line e.g. red,yellow,orange green blue… |
string |
coordinatesPolylines |
List of strings where each string is a lists of points encoded with Google Polyline Encoding |
string |
3.36. Vehicle
| Name | Description | Schema |
|---|---|---|
availability |
Determines the time, when the vehicle is available |
|
basicVehicleInfo |
Vehicle properties used to compute the optimal routes on the road from one point to another |
|
costsPerStop |
Costs of the vehicle per stop |
number(double) |
doNotFinishAtDepot |
Whether the vehicle should return to the depot after the last order on the last route |
boolean |
drivingTimeLimitation |
Determine driving time limits |
|
fixedCosts |
Fixed costs for using the vehicle. Not taken into account if the vehicle is not used for routing. |
number(double) |
id |
arbitrary id of the vehicle |
string |
lastStop |
Forces this location to be the last stop of the route (when doNotFinishAtDepot is true), or the second-to-last stop (when doNotFinishAtDepot is false, in which case the last stop is the depot) |
|
loadCosts |
Costs of the load for deliveries |
|
loadCostsBack |
Costs of the load for pickups |
|
maxLoad |
maximum load, i.e. capacity of the vehicle |
|
maxRoutes |
Maximumum number of routes for this vehicle |
integer(int32) |
skipLastLegFinishingAtDepot |
Whether the last leg should be included in the metrics and traces, only applicable when doNotFinishAtDepot is false |
boolean |
timeAtDepotSeconds |
When defined, changes the loading time at depot this fixed value in seconds and unloading time at depot to zero |
integer(int32) |
usageTimeLimitation |
Determine usage time limits |
|
vehicleTypes |
List of strings where each string is a flag representing a vehicle capability. e.g crane, refrigerator,… |
< string > array |
3.37. Violation
A Violation is when a road limitation is not respected, e.g. a road where the maximum gross weight of the vehicle exceeds the road limitation.
| Name | Description | Schema |
|---|---|---|
coordinates |
Point where the violation happened |
|
type |
Type of the limitation which is not respected, e.g. maxweight,toll,etc |
string |
value |
Value of the limitation which is not respected, e.g.in case of a maxweight limitation, 3.5 would be a common values |
number(double) |
3.38. VrpRequest
| Name | Description | Schema |
|---|---|---|
depot |
Depot, i.e. starting point of each route |
|
detailedTraces |
Whether the routes returned should include metrics and waypoints (true) or should include only metrics (false) |
boolean |
engine |
optimization engine. Valid values are RinkaiOpt(default),Brute and NoOp |
string |
flags |
debug/dev flags |
string |
locationsAndOrders |
List of orders to be picked or delivered |
|
vehicles |
List of vehicles available. If not specified, a single vehicle is used |
3.39. VrpResponse
The result of the optimization. It contains some meta information such as errors on individual orders, and a plan which is a near-optimal solution.
| Name | Description | Schema |
|---|---|---|
fullyPlanned |
Indicates whether all the locations and orders are included in the solution |
boolean |
generalError |
Describes the error in case a solution could not be provided at all |
|
invalidLocations |
List of location and orders which could not be included in the solution, and the reason |
|
plan |
Solution for the optimization request |
|
request |
The optimization request, with geocoded locations |
|
stats |
Stats e.g. time spent, credits left… |