This documentation presents the REST APIs of TourSolver Cloud.
The REST APIs provide programmatic access to creation, launching and reading of TourSolver optimizations. Thus you’ll be able to plan and optimize order deliveries while conforming to many constraints, defined on customers, resources and depots. You can also use this API to publish your optimized tour plans to Toursolver Mobile App and follow the fulfilment.
The main services are :
- optimize : send your data and start the optimization
- status : follow the optimization process (cost, distance and time evolution)
- stop : you can set a maximum optimization time, but you can also stop the optimization when you decide (ex: if global cost has not changed for a while)
- result / toursResult : retrieve the optimized result (bulk or tour organized)
- exportToOperationalPlanning : publish the result on Toursolver Mobile app
- fulfillment : follow the fulfillment of the tours by yours resources on the field
If you don’t need to follow the optimization process, you can use our webhook system : just start the optimization and the result will be automatically posted when ready to your server.
If you don’t want to build a result page, just integrate Toursolver result page in your app (more details in the tutorial).
Web APIs for TourSolver Cloud
In order to be able to use this api, you must provide your api key through the tsCloudApiKey parameter. This parameter can be passed either in the query or as a http header.
Caution : if you send to many requests in a short time, you may receive a 429 http code. When it happens, that means that your request as not been treated, you will have to send it again later.
This section presents the services.
This API consumes and produces json and xml. To specify the format you want to use, just add HTTP headers Accept and Content-Type.
- If you use json, you should add these headers :
-
- Accept: application/json
- Content-Type: application/json
- If you use xml, you should add these headers :
-
- Accept: application/xml
- Content-Type: application/xml
- The root url for this API is :
-
-
https://api.geoconcept.com/tsapi/ for most of the world.
Note: the former api URL (https://geoservices.geoconcept.com/ToursolverCloud/api/ts/toursolver/) is still working but will be removed in the future.
- https://geoservices.geoconcept.cn/ToursolverCloud/api/ts/toursolver/ for China only.
-
- Webhook integration :
- Webhook allow you to automatically receive optimization result when optimization finishes. Rather than requiring you to pull information via our API, webhooks will push information to your endpoint. ToursolverCloud will send a HTTP POST payload to the webhook’s configured in ToursolverCloud configuration menu. You will be able to specify in your optimization request if you want the result to be sent automatically to this webhook when the optimization ends and what result type you need (orders list or shipments list). Have a look to the sendResultToWeebhook parameter of the TSOptions object for more details.
- Webhooks retry logic is as follows :
- In case the original notification sending attempt fails (due to receiving a non-2xx response code or exceeding timeout of 10 seconds), we will try 3 more times: after 3, 30 and 150 seconds. If it still fails for each of those attempts, the webhook will be disabled and an email will be sent to warn you.
Toursolver optimization web service.
Type | Name | Description | Schema | Default |
---|---|---|---|---|
Body |
body |
visits to add, with id of target simulation or job, and language code |
-
application/xml
-
application/json
-
text/xml
-
application/xml
-
application/json
-
text/xml
Example HTTP request =.Request body
{ "id" : "...", "orders" : [ { "allSkillsRequired" : true, "assignResources" : [ "...", "..." ], "courierPenalty" : 12345.0, "customDataMap" : { "property1" : "...", "property2" : "..." }, "delayPenaltyPerHour" : 12345.0, "excludeResources" : [ "...", "..." ], "fixedVisitDuration" : "...", "frequency" : "...", "id" : "...", "minDuration" : "...", "minPartDuration" : "...", "punctuality" : 12345, "quantities" : [ 12345.0, 12345.0 ], "requiredSkills" : [ "...", "..." ], "resourceCompatibility" : 12345.0, "sequenceNumber" : 12345, "timeWindows" : [ { "beginTime" : "08:00", "endTime" : "18:00" }, { "beginTime" : "08:00", "endTime" : "18:00" } ], "travelTimeModifier" : { "offset" : "...", "value" : 12345.0, "length" : "..." }, "type" : 12345, "unloadingDurationPerUnit" : "...", "x" : 12345.0, "y" : 12345.0, "active" : true, "wholeVisitInTimeWindow" : true, "label" : "...", "evaluationInfos" : { "orderOriginalResourceId" : "...", "orderOriginalVisitDay" : "...", "orderPosition" : 12345 }, "possibleVisitDaysList" : [ "...", "..." ], "tsOrderMaximumSpacing" : 12345, "tsOrderMinimumSpacing" : 12345, "tsOrderLastVisit" : 12345, "customerId" : "...", "email" : "...", "phone" : "...", "tsOrderBefore" : "...", "tsOrderBeforeMaxTimeSpacing" : "...", "tsOrderBeforeMinTimeSpacing" : "...", "getNotifications" : true, "tsOrderFixed" : true }, { "allSkillsRequired" : true, "assignResources" : [ "...", "..." ], "courierPenalty" : 12345.0, "customDataMap" : { "property1" : "...", "property2" : "..." }, "delayPenaltyPerHour" : 12345.0, "excludeResources" : [ "...", "..." ], "fixedVisitDuration" : "...", "frequency" : "...", "id" : "...", "minDuration" : "...", "minPartDuration" : "...", "punctuality" : 12345, "quantities" : [ 12345.0, 12345.0 ], "requiredSkills" : [ "...", "..." ], "resourceCompatibility" : 12345.0, "sequenceNumber" : 12345, "timeWindows" : [ { "beginTime" : "08:00", "endTime" : "18:00" }, { "beginTime" : "08:00", "endTime" : "18:00" } ], "travelTimeModifier" : { "offset" : "...", "value" : 12345.0, "length" : "..." }, "type" : 12345, "unloadingDurationPerUnit" : "...", "x" : 12345.0, "y" : 12345.0, "active" : true, "wholeVisitInTimeWindow" : true, "label" : "...", "evaluationInfos" : { "orderOriginalResourceId" : "...", "orderOriginalVisitDay" : "...", "orderPosition" : 12345 }, "possibleVisitDaysList" : [ "...", "..." ], "tsOrderMaximumSpacing" : 12345, "tsOrderMinimumSpacing" : 12345, "tsOrderLastVisit" : 12345, "customerId" : "...", "email" : "...", "phone" : "...", "tsOrderBefore" : "...", "tsOrderBeforeMaxTimeSpacing" : "...", "tsOrderBeforeMinTimeSpacing" : "...", "getNotifications" : true, "tsOrderFixed" : true } ], "language" : "..." }
Example HTTP response =.Response 201
{ "application/json" : { "status" : "...", "message" : "..." } }
GET /toursolver/depots
Description Get known depots
Get depots defined in ToursolverCloud GUI.
Type | Name | Description | Schema | Default |
---|---|---|---|---|
Query |
depotName |
if a depot name is specified only one depot will be returned. |
string |
-
application/xml
-
application/json
-
text/xml
Example HTTP response =.Response 200
{ "application/json" : { "depots" : [ { "id" : "...", "openingDaysList" : [ "...", "..." ], "timeWindows" : [ { "beginTime" : "08:00", "endTime" : "18:00" }, { "beginTime" : "08:00", "endTime" : "18:00" } ], "availability" : true, "resourceNames" : "...", "excludeResources" : "...", "travelTimeModifier" : { "offset" : "...", "value" : 12345.0, "length" : "..." }, "fixedLoadingDuration" : "...", "loadingDurationPerUnit" : "...", "priority" : 12345, "requiredProducts" : "...", "allProductsRequired" : true, "deliveryQuantities" : [ 12345, 12345 ], "pickupQuantities" : [ 12345, 12345 ], "x" : 12345.0, "y" : 12345.0 }, { "id" : "...", "openingDaysList" : [ "...", "..." ], "timeWindows" : [ { "beginTime" : "08:00", "endTime" : "18:00" }, { "beginTime" : "08:00", "endTime" : "18:00" } ], "availability" : true, "resourceNames" : "...", "excludeResources" : "...", "travelTimeModifier" : { "offset" : "...", "value" : 12345.0, "length" : "..." }, "fixedLoadingDuration" : "...", "loadingDurationPerUnit" : "...", "priority" : 12345, "requiredProducts" : "...", "allProductsRequired" : true, "deliveryQuantities" : [ 12345, 12345 ], "pickupQuantities" : [ 12345, 12345 ], "x" : 12345.0, "y" : 12345.0 } ], "message" : "...", "status" : "ERROR" } }
POST /toursolver/exportToOperationalPlanning
Description Export to operational planning.
Exports the result of an optimization to operational planning that mobile resources will be able to browse on the field through a mobile app.
This command only works on completed optimizations. Mobile resource identifiers must have been set previously in TsCloud app. If optimization period overlaps an already existing operational planning, export will work only if the force attribut has been set to true.
-
application/xml
-
application/json
-
text/xml
-
application/xml
-
application/json
-
text/xml
Example HTTP request =.Request body
{ "resourceMapping" : [ { "id" : "...", "operationalId" : "..." }, { "id" : "...", "operationalId" : "..." } ], "startDate" : 12345, "force" : true, "taskId" : "...", "dayNums" : [ 12345, 12345 ] }
Example HTTP response =.Response 201
{ "application/json" : { "message" : "...", "status" : "OK" } }
GET /toursolver/fulfillment
Description Get fulfillment information.
Get fulfillment information for a specified period of time.
Type | Name | Description | Schema | Default |
---|---|---|---|---|
Query |
endDate |
planning period end |
string |
|
Query |
lastUpdate |
if specified, only operationalOrders that have been modified since this date will be returned. |
string |
|
Query |
startDate |
planning period start |
string |
|
Query |
userLogin |
a mobile resource login (optional) |
string |
-
application/xml
-
application/json
-
text/xml
Example HTTP response =.Response 200
{ "application/json" : { "operationalOrderAchievements" : [ { "operationalResourceId" : "...", "plannedOrder" : { "dayId" : "...", "stopPosition" : 12345, "stopY" : 12345.0, "stopX" : 12345.0, "stopId" : "...", "stopType" : 12345, "stopDriveTime" : "...", "stopStartTime" : "...", "stopDuration" : "...", "stopStatus" : 12345, "stopDriveDistance" : 12345, "stopElapsedDistance" : 12345, "resourceId" : "..." }, "order" : { "allSkillsRequired" : true, "assignResources" : [ "...", "..." ], "courierPenalty" : 12345.0, "customDataMap" : { "property1" : "...", "property2" : "..." }, "delayPenaltyPerHour" : 12345.0, "excludeResources" : [ "...", "..." ], "fixedVisitDuration" : "...", "frequency" : "...", "id" : "...", "minDuration" : "...", "minPartDuration" : "...", "punctuality" : 12345, "quantities" : [ 12345.0, 12345.0 ], "requiredSkills" : [ "...", "..." ], "resourceCompatibility" : 12345.0, "sequenceNumber" : 12345, "timeWindows" : [ { }, { } ], "travelTimeModifier" : { }, "type" : 12345, "unloadingDurationPerUnit" : "...", "x" : 12345.0, "y" : 12345.0, "active" : true, "wholeVisitInTimeWindow" : true, "label" : "...", "evaluationInfos" : { }, "possibleVisitDaysList" : [ "...", "..." ], "tsOrderMaximumSpacing" : 12345, "tsOrderMinimumSpacing" : 12345, "tsOrderLastVisit" : 12345, "customerId" : "...", "email" : "...", "phone" : "...", "tsOrderBefore" : "...", "tsOrderBeforeMaxTimeSpacing" : "...", "tsOrderBeforeMinTimeSpacing" : "...", "getNotifications" : true, "tsOrderFixed" : true }, "date" : 12345, "start" : 12345, "end" : 12345, "status" : "FINISHED", "type" : "LUNCHBREAK", "lon" : 12345.0, "lat" : 12345.0, "lastSynchroStatusChange" : 12345, "synchroStatus" : "PUBLISHED", "achievementStart" : 12345, "achievementEnd" : 12345, "achievementComment" : "...", "achievementStartLat" : 12345.0, "achievementStartLon" : 12345.0, "achievementEndLat" : 12345.0, "achievementEndLon" : 12345.0, "geocode" : { "addressComplement" : "...", "address" : "...", "postcode" : "...", "city" : "...", "region" : "...", "country" : "...", "score" : 12345.0, "geocodeType" : 12345, "geocodeCity" : "...", "geocodePostalCode" : "...", "geocodeAddressLine" : "..." }, "signatureSvg" : "...", "signaturePicture" : "...", "data" : { "property1" : "...", "property2" : "..." }, "pictures" : [ "...", "..." ], "simulationId" : "...", "simulationDayId" : "...", "timeWindowEnd" : 12345, "timeWindowSmsId" : "...", "timeWindowSmsStatus" : "...", "timeWindowStart" : 12345, "apprauchSmsId" : "...", "apprauchSmsStatus" : "...", "feedbackSmsId" : "...", "feedbackSmsStatus" : "...", "id" : "..." }, { "operationalResourceId" : "...", "plannedOrder" : { "dayId" : "...", "stopPosition" : 12345, "stopY" : 12345.0, "stopX" : 12345.0, "stopId" : "...", "stopType" : 12345, "stopDriveTime" : "...", "stopStartTime" : "...", "stopDuration" : "...", "stopStatus" : 12345, "stopDriveDistance" : 12345, "stopElapsedDistance" : 12345, "resourceId" : "..." }, "order" : { "allSkillsRequired" : true, "assignResources" : [ "...", "..." ], "courierPenalty" : 12345.0, "customDataMap" : { "property1" : "...", "property2" : "..." }, "delayPenaltyPerHour" : 12345.0, "excludeResources" : [ "...", "..." ], "fixedVisitDuration" : "...", "frequency" : "...", "id" : "...", "minDuration" : "...", "minPartDuration" : "...", "punctuality" : 12345, "quantities" : [ 12345.0, 12345.0 ], "requiredSkills" : [ "...", "..." ], "resourceCompatibility" : 12345.0, "sequenceNumber" : 12345, "timeWindows" : [ { }, { } ], "travelTimeModifier" : { }, "type" : 12345, "unloadingDurationPerUnit" : "...", "x" : 12345.0, "y" : 12345.0, "active" : true, "wholeVisitInTimeWindow" : true, "label" : "...", "evaluationInfos" : { }, "possibleVisitDaysList" : [ "...", "..." ], "tsOrderMaximumSpacing" : 12345, "tsOrderMinimumSpacing" : 12345, "tsOrderLastVisit" : 12345, "customerId" : "...", "email" : "...", "phone" : "...", "tsOrderBefore" : "...", "tsOrderBeforeMaxTimeSpacing" : "...", "tsOrderBeforeMinTimeSpacing" : "...", "getNotifications" : true, "tsOrderFixed" : true }, "date" : 12345, "start" : 12345, "end" : 12345, "status" : "REFUSED", "type" : "RELOADBREAK", "lon" : 12345.0, "lat" : 12345.0, "lastSynchroStatusChange" : 12345, "synchroStatus" : "UPDATED", "achievementStart" : 12345, "achievementEnd" : 12345, "achievementComment" : "...", "achievementStartLat" : 12345.0, "achievementStartLon" : 12345.0, "achievementEndLat" : 12345.0, "achievementEndLon" : 12345.0, "geocode" : { "addressComplement" : "...", "address" : "...", "postcode" : "...", "city" : "...", "region" : "...", "country" : "...", "score" : 12345.0, "geocodeType" : 12345, "geocodeCity" : "...", "geocodePostalCode" : "...", "geocodeAddressLine" : "..." }, "signatureSvg" : "...", "signaturePicture" : "...", "data" : { "property1" : "...", "property2" : "..." }, "pictures" : [ "...", "..." ], "simulationId" : "...", "simulationDayId" : "...", "timeWindowEnd" : 12345, "timeWindowSmsId" : "...", "timeWindowSmsStatus" : "...", "timeWindowStart" : 12345, "apprauchSmsId" : "...", "apprauchSmsStatus" : "...", "feedbackSmsId" : "...", "feedbackSmsStatus" : "...", "id" : "..." } ], "lastKnownPosition" : [ { "date" : 12345, "lon" : 12345.0, "lat" : 12345.0, "accuracy" : 12345.0, "privateLife" : true, "gpsStatus" : "0", "batteryLevel" : 12345, "id" : "..." }, { "date" : 12345, "lon" : 12345.0, "lat" : 12345.0, "accuracy" : 12345.0, "privateLife" : true, "gpsStatus" : "0", "batteryLevel" : 12345, "id" : "..." } ], "message" : "...", "status" : "OK" } }
GET /toursolver/gatewayToken
Description Get a gateway token.
Get a gateway token that can be used to get connected to Toursolver GUI through the gateway.
Use this token to get connected to TsCloud GUI by passing it in the query like this : https://app.geoconcept.com/ToursolverCloud/ts/login?token=xxx
Note : this token will not work with the old (geoservices) Toursolver url.
Type | Name | Description | Schema | Default |
---|---|---|---|---|
Query |
login |
in multi-user context, you can specify the login. If not specified, the default user will be used. |
string |
-
application/xml
-
application/json
-
text/xml
Example HTTP response =.Response 200
{ "application/json" : { "token" : "...", "validUntil" : 12345, "message" : "...", "status" : "ERROR" } }
GET /toursolver/logintoken
Description [DEPRECATED] Get a login token.
Get a login token that can be used to get connected to Toursolver GUI. This token has a 30s life time.
Use this token to get connected to TsCloud GUI by passing it in the query like this : https://geoservices.geoconcept.com/ToursolverCloud/ts/login?token=xxx
This method is deprecated and will be removed in the future, it works only with the old (geoservices) Toursolver url, you should use gatewayToken instead.
Type | Name | Description | Schema | Default |
---|---|---|---|---|
Query |
login |
in multi-user context, you can specify the login. If not specified, the default user will be used. |
string |
-
application/xml
-
application/json
-
text/xml
Example HTTP response =.Response 200
{ "application/json" : { "token" : "...", "validUntil" : 12345, "message" : "...", "status" : "ERROR" } }
POST /toursolver/optimize
Description Start Optimization.
Launch Toursolver planning optimization : starts the planning process on Orders and Resources data.
Use this method to plan tours. The process consists in assigning Orders object elements to Resources object on a way that respects the constraints and minimizes the cost of the computed planning. This method is composed of 2 processes: a data checking and optimizing process.
Type | Name | Description | Schema | Default |
---|---|---|---|---|
Body |
body |
Optimization request with all constraints |
-
application/xml
-
application/json
-
text/xml
-
application/xml
-
application/json
-
text/xml
Example HTTP request =.Request body
{ "depots" : [ { "id" : "...", "openingDaysList" : [ "...", "..." ], "timeWindows" : [ { "beginTime" : "08:00", "endTime" : "18:00" }, { "beginTime" : "08:00", "endTime" : "18:00" } ], "availability" : true, "resourceNames" : "...", "excludeResources" : "...", "travelTimeModifier" : { "offset" : "...", "value" : 12345.0, "length" : "..." }, "fixedLoadingDuration" : "...", "loadingDurationPerUnit" : "...", "priority" : 12345, "requiredProducts" : "...", "allProductsRequired" : true, "deliveryQuantities" : [ 12345, 12345 ], "pickupQuantities" : [ 12345, 12345 ], "x" : 12345.0, "y" : 12345.0 }, { "id" : "...", "openingDaysList" : [ "...", "..." ], "timeWindows" : [ { "beginTime" : "08:00", "endTime" : "18:00" }, { "beginTime" : "08:00", "endTime" : "18:00" } ], "availability" : true, "resourceNames" : "...", "excludeResources" : "...", "travelTimeModifier" : { "offset" : "...", "value" : 12345.0, "length" : "..." }, "fixedLoadingDuration" : "...", "loadingDurationPerUnit" : "...", "priority" : 12345, "requiredProducts" : "...", "allProductsRequired" : true, "deliveryQuantities" : [ 12345, 12345 ], "pickupQuantities" : [ 12345, 12345 ], "x" : 12345.0, "y" : 12345.0 } ], "orders" : [ { "allSkillsRequired" : true, "assignResources" : [ "...", "..." ], "courierPenalty" : 12345.0, "customDataMap" : { "property1" : "...", "property2" : "..." }, "delayPenaltyPerHour" : 12345.0, "excludeResources" : [ "...", "..." ], "fixedVisitDuration" : "...", "frequency" : "...", "id" : "...", "minDuration" : "...", "minPartDuration" : "...", "punctuality" : 12345, "quantities" : [ 12345.0, 12345.0 ], "requiredSkills" : [ "...", "..." ], "resourceCompatibility" : 12345.0, "sequenceNumber" : 12345, "timeWindows" : [ { "beginTime" : "08:00", "endTime" : "18:00" }, { "beginTime" : "08:00", "endTime" : "18:00" } ], "travelTimeModifier" : { "offset" : "...", "value" : 12345.0, "length" : "..." }, "type" : 12345, "unloadingDurationPerUnit" : "...", "x" : 12345.0, "y" : 12345.0, "active" : true, "wholeVisitInTimeWindow" : true, "label" : "...", "evaluationInfos" : { "orderOriginalResourceId" : "...", "orderOriginalVisitDay" : "...", "orderPosition" : 12345 }, "possibleVisitDaysList" : [ "...", "..." ], "tsOrderMaximumSpacing" : 12345, "tsOrderMinimumSpacing" : 12345, "tsOrderLastVisit" : 12345, "customerId" : "...", "email" : "...", "phone" : "...", "tsOrderBefore" : "...", "tsOrderBeforeMaxTimeSpacing" : "...", "tsOrderBeforeMinTimeSpacing" : "...", "getNotifications" : true, "tsOrderFixed" : true }, { "allSkillsRequired" : true, "assignResources" : [ "...", "..." ], "courierPenalty" : 12345.0, "customDataMap" : { "property1" : "...", "property2" : "..." }, "delayPenaltyPerHour" : 12345.0, "excludeResources" : [ "...", "..." ], "fixedVisitDuration" : "...", "frequency" : "...", "id" : "...", "minDuration" : "...", "minPartDuration" : "...", "punctuality" : 12345, "quantities" : [ 12345.0, 12345.0 ], "requiredSkills" : [ "...", "..." ], "resourceCompatibility" : 12345.0, "sequenceNumber" : 12345, "timeWindows" : [ { "beginTime" : "08:00", "endTime" : "18:00" }, { "beginTime" : "08:00", "endTime" : "18:00" } ], "travelTimeModifier" : { "offset" : "...", "value" : 12345.0, "length" : "..." }, "type" : 12345, "unloadingDurationPerUnit" : "...", "x" : 12345.0, "y" : 12345.0, "active" : true, "wholeVisitInTimeWindow" : true, "label" : "...", "evaluationInfos" : { "orderOriginalResourceId" : "...", "orderOriginalVisitDay" : "...", "orderPosition" : 12345 }, "possibleVisitDaysList" : [ "...", "..." ], "tsOrderMaximumSpacing" : 12345, "tsOrderMinimumSpacing" : 12345, "tsOrderLastVisit" : 12345, "customerId" : "...", "email" : "...", "phone" : "...", "tsOrderBefore" : "...", "tsOrderBeforeMaxTimeSpacing" : "...", "tsOrderBeforeMinTimeSpacing" : "...", "getNotifications" : true, "tsOrderFixed" : true } ], "resources" : [ { "available" : true, "avgConsumption" : 8.0, "briefingDuration" : "00:20:00", "capacities" : [ 12.0, 12.0 ], "providedSkills" : "...", "customDataMap" : { "property1" : "...", "property2" : "..." }, "dailyWorkTime" : "...", "debriefingDuration" : "...", "driveRestAtCustomer" : true, "driveRestAtDepot" : true, "fixedLoadingDuration" : "...", "fuelType" : 12345, "id" : "...", "legalDailyDriveDuration" : "...", "legalDailyRestDuration" : "...", "legalDriveRestDuration" : "...", "legalMaxDriveDuration" : "00:30:00", "legalMinRestDuration" : "...", "loadBeforeDeparture" : true, "loadingDurationPerUnit" : "...", "loadOnReturn" : true, "lunch" : { "start" : "12:30", "end" : "14:00", "duration" : "60" }, "maxNightsOutPerJourney" : 12345, "minDriveDuration" : "...", "nightPenalty" : 12345.0, "nonUsePenalty" : 12345.0, "openStart" : true, "openStop" : true, "optimumStartTime" : true, "overnightMinDriving" : "...", "overtimeDurations" : [ { }, { } ], "overtimePenalties" : [ 12345.0, 12345.0 ], "payWholeDay" : true, "penaltyPerVisit" : 12345.0, "speedAdjustment" : 12345, "startTravelTimeModifier" : { "offset" : "...", "value" : 12345.0, "length" : "..." }, "stopTravelTimeModifier" : { "offset" : "...", "value" : 12345.0, "length" : "..." }, "extraTravelPenalties" : [ { "distance" : 12345, "penalty" : 12345.0 }, { "distance" : 12345, "penalty" : 12345.0 } ], "travelTimeModifier" : { "offset" : "...", "value" : 12345.0, "length" : "..." }, "usePenalty" : 12345.0, "weeklyWorkTime" : "...", "workEndTime" : "...", "workingDays" : "...", "workPenalty" : 12345.0, "workStartTime" : "...", "startX" : 12345.0, "endX" : 12345.0, "startY" : 12345.0, "endY" : 12345.0, "travelPenalty" : 12345.0, "minimumQuantity" : 12345.0, "fixedUnloadingDuration" : "...", "unloadingDurationPerUnit" : "...", "maximumReloads" : 12345, "maximumReloadsPenalty" : 12345.0, "noReload" : true, "otherWorkStartTimes" : "...", "otherWorkEndTimes" : "...", "otherWorkingDays" : [ "...", "..." ], "providedProducts" : "...", "useInPlanningPenalty" : 12345.0, "maximumDistance" : 12345, "maximumVisits" : 12345, "mobileLogin" : "...", "useAllCapacities" : true, "globalCapacity" : 12345.0, "additionalCostOrderCustomDataName" : "...", "additionalCostOperator" : "MAX", "additionalCosts" : [ { "type" : "...", "value" : 12345.0 }, { "type" : "...", "value" : 12345.0 } ], "openTimeStart" : true, "openDistanceStart" : true, "openTimeStop" : true, "openDistanceStop" : true, "tomTomWebFleetEnabled" : true, "tomTomWebFleetIdentifier" : "...", "vehicleCode" : "...", "fuelCode" : "..." }, { "available" : true, "avgConsumption" : 8.0, "briefingDuration" : "00:20:00", "capacities" : [ 12.0, 12.0 ], "providedSkills" : "...", "customDataMap" : { "property1" : "...", "property2" : "..." }, "dailyWorkTime" : "...", "debriefingDuration" : "...", "driveRestAtCustomer" : true, "driveRestAtDepot" : true, "fixedLoadingDuration" : "...", "fuelType" : 12345, "id" : "...", "legalDailyDriveDuration" : "...", "legalDailyRestDuration" : "...", "legalDriveRestDuration" : "...", "legalMaxDriveDuration" : "00:30:00", "legalMinRestDuration" : "...", "loadBeforeDeparture" : true, "loadingDurationPerUnit" : "...", "loadOnReturn" : true, "lunch" : { "start" : "12:30", "end" : "14:00", "duration" : "60" }, "maxNightsOutPerJourney" : 12345, "minDriveDuration" : "...", "nightPenalty" : 12345.0, "nonUsePenalty" : 12345.0, "openStart" : true, "openStop" : true, "optimumStartTime" : true, "overnightMinDriving" : "...", "overtimeDurations" : [ { }, { } ], "overtimePenalties" : [ 12345.0, 12345.0 ], "payWholeDay" : true, "penaltyPerVisit" : 12345.0, "speedAdjustment" : 12345, "startTravelTimeModifier" : { "offset" : "...", "value" : 12345.0, "length" : "..." }, "stopTravelTimeModifier" : { "offset" : "...", "value" : 12345.0, "length" : "..." }, "extraTravelPenalties" : [ { "distance" : 12345, "penalty" : 12345.0 }, { "distance" : 12345, "penalty" : 12345.0 } ], "travelTimeModifier" : { "offset" : "...", "value" : 12345.0, "length" : "..." }, "usePenalty" : 12345.0, "weeklyWorkTime" : "...", "workEndTime" : "...", "workingDays" : "...", "workPenalty" : 12345.0, "workStartTime" : "...", "startX" : 12345.0, "endX" : 12345.0, "startY" : 12345.0, "endY" : 12345.0, "travelPenalty" : 12345.0, "minimumQuantity" : 12345.0, "fixedUnloadingDuration" : "...", "unloadingDurationPerUnit" : "...", "maximumReloads" : 12345, "maximumReloadsPenalty" : 12345.0, "noReload" : true, "otherWorkStartTimes" : "...", "otherWorkEndTimes" : "...", "otherWorkingDays" : [ "...", "..." ], "providedProducts" : "...", "useInPlanningPenalty" : 12345.0, "maximumDistance" : 12345, "maximumVisits" : 12345, "mobileLogin" : "...", "useAllCapacities" : true, "globalCapacity" : 12345.0, "additionalCostOrderCustomDataName" : "...", "additionalCostOperator" : "AVERAGE", "additionalCosts" : [ { "type" : "...", "value" : 12345.0 }, { "type" : "...", "value" : 12345.0 } ], "openTimeStart" : true, "openDistanceStart" : true, "openTimeStop" : true, "openDistanceStop" : true, "tomTomWebFleetEnabled" : true, "tomTomWebFleetIdentifier" : "...", "vehicleCode" : "...", "fuelCode" : "..." } ], "options" : { "evaluation" : true, "startFromEvaluationInfo" : true, "maxOptimDuration" : "...", "reloadDuration" : "...", "noReload" : true, "distanceType" : "METERS", "teamId" : "...", "sendResultToWebhook" : "ORDERS", "countVisitCostOnceIfSameLocation" : true, "countDepotsInDeliveryCost" : "FIRST", "excludeVisitCostIfMaxAdditionalCost" : true, "routingMethod" : "DISTANCE", "allowToll" : true, "allowTunnel" : true, "allowBridge" : true, "vehicleCode" : "...", "fuelCode" : "...", "speedPattern" : "...", "useForbiddenTransitAreas" : true, "useOTSolver" : true, "balanceType" : "HOURS", "balanceValue" : 12345 }, "countryCode" : "...", "simulationName" : "...", "language" : "...", "beginDate" : 12345, "userLogin" : "...", "organization" : "..." }
Example HTTP response =.Response 201
{ "application/json" : { "taskId" : "...", "message" : "...", "status" : "OK" } }
GET /toursolver/resources
Description Get known resources
Get resources defined in ToursolverCloud GUI.
Type | Name | Description | Schema | Default |
---|---|---|---|---|
Query |
resourceName |
if a resource name is specified (team name will be ignored), only one resource will be returned. |
string |
|
Query |
teamName |
if a team name is specified, only the resources of this team will returned |
string |
-
application/xml
-
application/json
-
text/xml
Example HTTP response =.Response 200
{ "application/json" : { "resources" : [ { "available" : true, "avgConsumption" : 8.0, "briefingDuration" : "00:20:00", "capacities" : [ 12.0, 12.0 ], "providedSkills" : "...", "customDataMap" : { "property1" : "...", "property2" : "..." }, "dailyWorkTime" : "...", "debriefingDuration" : "...", "driveRestAtCustomer" : true, "driveRestAtDepot" : true, "fixedLoadingDuration" : "...", "fuelType" : 12345, "id" : "...", "legalDailyDriveDuration" : "...", "legalDailyRestDuration" : "...", "legalDriveRestDuration" : "...", "legalMaxDriveDuration" : "00:30:00", "legalMinRestDuration" : "...", "loadBeforeDeparture" : true, "loadingDurationPerUnit" : "...", "loadOnReturn" : true, "lunch" : { "start" : "12:30", "end" : "14:00", "duration" : "60" }, "maxNightsOutPerJourney" : 12345, "minDriveDuration" : "...", "nightPenalty" : 12345.0, "nonUsePenalty" : 12345.0, "openStart" : true, "openStop" : true, "optimumStartTime" : true, "overnightMinDriving" : "...", "overtimeDurations" : [ { }, { } ], "overtimePenalties" : [ 12345.0, 12345.0 ], "payWholeDay" : true, "penaltyPerVisit" : 12345.0, "speedAdjustment" : 12345, "startTravelTimeModifier" : { "offset" : "...", "value" : 12345.0, "length" : "..." }, "stopTravelTimeModifier" : { "offset" : "...", "value" : 12345.0, "length" : "..." }, "extraTravelPenalties" : [ { "distance" : 12345, "penalty" : 12345.0 }, { "distance" : 12345, "penalty" : 12345.0 } ], "travelTimeModifier" : { "offset" : "...", "value" : 12345.0, "length" : "..." }, "usePenalty" : 12345.0, "weeklyWorkTime" : "...", "workEndTime" : "...", "workingDays" : "...", "workPenalty" : 12345.0, "workStartTime" : "...", "startX" : 12345.0, "endX" : 12345.0, "startY" : 12345.0, "endY" : 12345.0, "travelPenalty" : 12345.0, "minimumQuantity" : 12345.0, "fixedUnloadingDuration" : "...", "unloadingDurationPerUnit" : "...", "maximumReloads" : 12345, "maximumReloadsPenalty" : 12345.0, "noReload" : true, "otherWorkStartTimes" : "...", "otherWorkEndTimes" : "...", "otherWorkingDays" : [ "...", "..." ], "providedProducts" : "...", "useInPlanningPenalty" : 12345.0, "maximumDistance" : 12345, "maximumVisits" : 12345, "mobileLogin" : "...", "useAllCapacities" : true, "globalCapacity" : 12345.0, "additionalCostOrderCustomDataName" : "...", "additionalCostOperator" : "MAX", "additionalCosts" : [ { "type" : "...", "value" : 12345.0 }, { "type" : "...", "value" : 12345.0 } ], "openTimeStart" : true, "openDistanceStart" : true, "openTimeStop" : true, "openDistanceStop" : true, "tomTomWebFleetEnabled" : true, "tomTomWebFleetIdentifier" : "...", "vehicleCode" : "...", "fuelCode" : "..." }, { "available" : true, "avgConsumption" : 8.0, "briefingDuration" : "00:20:00", "capacities" : [ 12.0, 12.0 ], "providedSkills" : "...", "customDataMap" : { "property1" : "...", "property2" : "..." }, "dailyWorkTime" : "...", "debriefingDuration" : "...", "driveRestAtCustomer" : true, "driveRestAtDepot" : true, "fixedLoadingDuration" : "...", "fuelType" : 12345, "id" : "...", "legalDailyDriveDuration" : "...", "legalDailyRestDuration" : "...", "legalDriveRestDuration" : "...", "legalMaxDriveDuration" : "00:30:00", "legalMinRestDuration" : "...", "loadBeforeDeparture" : true, "loadingDurationPerUnit" : "...", "loadOnReturn" : true, "lunch" : { "start" : "12:30", "end" : "14:00", "duration" : "60" }, "maxNightsOutPerJourney" : 12345, "minDriveDuration" : "...", "nightPenalty" : 12345.0, "nonUsePenalty" : 12345.0, "openStart" : true, "openStop" : true, "optimumStartTime" : true, "overnightMinDriving" : "...", "overtimeDurations" : [ { }, { } ], "overtimePenalties" : [ 12345.0, 12345.0 ], "payWholeDay" : true, "penaltyPerVisit" : 12345.0, "speedAdjustment" : 12345, "startTravelTimeModifier" : { "offset" : "...", "value" : 12345.0, "length" : "..." }, "stopTravelTimeModifier" : { "offset" : "...", "value" : 12345.0, "length" : "..." }, "extraTravelPenalties" : [ { "distance" : 12345, "penalty" : 12345.0 }, { "distance" : 12345, "penalty" : 12345.0 } ], "travelTimeModifier" : { "offset" : "...", "value" : 12345.0, "length" : "..." }, "usePenalty" : 12345.0, "weeklyWorkTime" : "...", "workEndTime" : "...", "workingDays" : "...", "workPenalty" : 12345.0, "workStartTime" : "...", "startX" : 12345.0, "endX" : 12345.0, "startY" : 12345.0, "endY" : 12345.0, "travelPenalty" : 12345.0, "minimumQuantity" : 12345.0, "fixedUnloadingDuration" : "...", "unloadingDurationPerUnit" : "...", "maximumReloads" : 12345, "maximumReloadsPenalty" : 12345.0, "noReload" : true, "otherWorkStartTimes" : "...", "otherWorkEndTimes" : "...", "otherWorkingDays" : [ "...", "..." ], "providedProducts" : "...", "useInPlanningPenalty" : 12345.0, "maximumDistance" : 12345, "maximumVisits" : 12345, "mobileLogin" : "...", "useAllCapacities" : true, "globalCapacity" : 12345.0, "additionalCostOrderCustomDataName" : "...", "additionalCostOperator" : "SUM", "additionalCosts" : [ { "type" : "...", "value" : 12345.0 }, { "type" : "...", "value" : 12345.0 } ], "openTimeStart" : true, "openDistanceStart" : true, "openTimeStop" : true, "openDistanceStop" : true, "tomTomWebFleetEnabled" : true, "tomTomWebFleetIdentifier" : "...", "vehicleCode" : "...", "fuelCode" : "..." } ], "message" : "...", "status" : "ERROR" } }
GET /toursolver/result
Description Get optimization result.
Get the result of planning optimization. Status of the optimization must be terminated.
Type | Name | Description | Schema | Default |
---|---|---|---|---|
Query |
taskId |
the id of optimization task, as returned by the optimize service |
string |
-
application/xml
-
application/json
-
text/xml
Example HTTP response =.Response 200
{ "application/json" : { "taskId" : "...", "plannedOrders" : [ { "dayId" : "...", "stopPosition" : 12345, "stopY" : 12345.0, "stopX" : 12345.0, "stopId" : "...", "stopType" : 12345, "stopDriveTime" : "...", "stopStartTime" : "...", "stopDuration" : "...", "stopStatus" : 12345, "stopDriveDistance" : 12345, "stopElapsedDistance" : 12345, "resourceId" : "..." }, { "dayId" : "...", "stopPosition" : 12345, "stopY" : 12345.0, "stopX" : 12345.0, "stopId" : "...", "stopType" : 12345, "stopDriveTime" : "...", "stopStartTime" : "...", "stopDuration" : "...", "stopStatus" : 12345, "stopDriveDistance" : 12345, "stopElapsedDistance" : 12345, "resourceId" : "..." } ], "unplannedOrders" : [ { "stopID" : "...", "reason" : "..." }, { "stopID" : "...", "reason" : "..." } ], "warnings" : [ { "objectType" : "...", "id" : "...", "constraint" : 12345, "value" : "...", "message" : "...", "messageId" : 12345, "i18nMessageCode" : "...", "constraintName" : "..." }, { "objectType" : "...", "id" : "...", "constraint" : 12345, "value" : "...", "message" : "...", "messageId" : 12345, "i18nMessageCode" : "...", "constraintName" : "..." } ], "simulationId" : "...", "message" : "...", "status" : "ERROR" } }
GET /toursolver/simulation
Description Get simulation by ID
Get simulation launched in ToursolverCloud (GUI).
-
application/xml
-
application/json
-
text/xml
Example HTTP response =.Response 200
{ "application/json" : { "simulation" : { "depots" : [ { "id" : "...", "openingDaysList" : [ "...", "..." ], "timeWindows" : [ { }, { } ], "availability" : true, "resourceNames" : "...", "excludeResources" : "...", "travelTimeModifier" : { }, "fixedLoadingDuration" : "...", "loadingDurationPerUnit" : "...", "priority" : 12345, "requiredProducts" : "...", "allProductsRequired" : true, "deliveryQuantities" : [ 12345, 12345 ], "pickupQuantities" : [ 12345, 12345 ], "x" : 12345.0, "y" : 12345.0 }, { "id" : "...", "openingDaysList" : [ "...", "..." ], "timeWindows" : [ { }, { } ], "availability" : true, "resourceNames" : "...", "excludeResources" : "...", "travelTimeModifier" : { }, "fixedLoadingDuration" : "...", "loadingDurationPerUnit" : "...", "priority" : 12345, "requiredProducts" : "...", "allProductsRequired" : true, "deliveryQuantities" : [ 12345, 12345 ], "pickupQuantities" : [ 12345, 12345 ], "x" : 12345.0, "y" : 12345.0 } ], "resources" : [ { "available" : true, "avgConsumption" : 8.0, "briefingDuration" : "00:20:00", "capacities" : [ 12.0, 12.0 ], "providedSkills" : "...", "customDataMap" : { "property1" : "...", "property2" : "..." }, "dailyWorkTime" : "...", "debriefingDuration" : "...", "driveRestAtCustomer" : true, "driveRestAtDepot" : true, "fixedLoadingDuration" : "...", "fuelType" : 12345, "id" : "...", "legalDailyDriveDuration" : "...", "legalDailyRestDuration" : "...", "legalDriveRestDuration" : "...", "legalMaxDriveDuration" : "00:30:00", "legalMinRestDuration" : "...", "loadBeforeDeparture" : true, "loadingDurationPerUnit" : "...", "loadOnReturn" : true, "lunch" : { }, "maxNightsOutPerJourney" : 12345, "minDriveDuration" : "...", "nightPenalty" : 12345.0, "nonUsePenalty" : 12345.0, "openStart" : true, "openStop" : true, "optimumStartTime" : true, "overnightMinDriving" : "...", "overtimeDurations" : [ { }, { } ], "overtimePenalties" : [ 12345.0, 12345.0 ], "payWholeDay" : true, "penaltyPerVisit" : 12345.0, "speedAdjustment" : 12345, "startTravelTimeModifier" : { }, "stopTravelTimeModifier" : { }, "extraTravelPenalties" : [ { }, { } ], "travelTimeModifier" : { }, "usePenalty" : 12345.0, "weeklyWorkTime" : "...", "workEndTime" : "...", "workingDays" : "...", "workPenalty" : 12345.0, "workStartTime" : "...", "startX" : 12345.0, "endX" : 12345.0, "startY" : 12345.0, "endY" : 12345.0, "travelPenalty" : 12345.0, "minimumQuantity" : 12345.0, "fixedUnloadingDuration" : "...", "unloadingDurationPerUnit" : "...", "maximumReloads" : 12345, "maximumReloadsPenalty" : 12345.0, "noReload" : true, "otherWorkStartTimes" : "...", "otherWorkEndTimes" : "...", "otherWorkingDays" : [ "...", "..." ], "providedProducts" : "...", "useInPlanningPenalty" : 12345.0, "maximumDistance" : 12345, "maximumVisits" : 12345, "mobileLogin" : "...", "useAllCapacities" : true, "globalCapacity" : 12345.0, "additionalCostOrderCustomDataName" : "...", "additionalCostOperator" : "MIN", "additionalCosts" : [ { }, { } ], "openTimeStart" : true, "openDistanceStart" : true, "openTimeStop" : true, "openDistanceStop" : true, "tomTomWebFleetEnabled" : true, "tomTomWebFleetIdentifier" : "...", "vehicleCode" : "...", "fuelCode" : "..." }, { "available" : true, "avgConsumption" : 8.0, "briefingDuration" : "00:20:00", "capacities" : [ 12.0, 12.0 ], "providedSkills" : "...", "customDataMap" : { "property1" : "...", "property2" : "..." }, "dailyWorkTime" : "...", "debriefingDuration" : "...", "driveRestAtCustomer" : true, "driveRestAtDepot" : true, "fixedLoadingDuration" : "...", "fuelType" : 12345, "id" : "...", "legalDailyDriveDuration" : "...", "legalDailyRestDuration" : "...", "legalDriveRestDuration" : "...", "legalMaxDriveDuration" : "00:30:00", "legalMinRestDuration" : "...", "loadBeforeDeparture" : true, "loadingDurationPerUnit" : "...", "loadOnReturn" : true, "lunch" : { }, "maxNightsOutPerJourney" : 12345, "minDriveDuration" : "...", "nightPenalty" : 12345.0, "nonUsePenalty" : 12345.0, "openStart" : true, "openStop" : true, "optimumStartTime" : true, "overnightMinDriving" : "...", "overtimeDurations" : [ { }, { } ], "overtimePenalties" : [ 12345.0, 12345.0 ], "payWholeDay" : true, "penaltyPerVisit" : 12345.0, "speedAdjustment" : 12345, "startTravelTimeModifier" : { }, "stopTravelTimeModifier" : { }, "extraTravelPenalties" : [ { }, { } ], "travelTimeModifier" : { }, "usePenalty" : 12345.0, "weeklyWorkTime" : "...", "workEndTime" : "...", "workingDays" : "...", "workPenalty" : 12345.0, "workStartTime" : "...", "startX" : 12345.0, "endX" : 12345.0, "startY" : 12345.0, "endY" : 12345.0, "travelPenalty" : 12345.0, "minimumQuantity" : 12345.0, "fixedUnloadingDuration" : "...", "unloadingDurationPerUnit" : "...", "maximumReloads" : 12345, "maximumReloadsPenalty" : 12345.0, "noReload" : true, "otherWorkStartTimes" : "...", "otherWorkEndTimes" : "...", "otherWorkingDays" : [ "...", "..." ], "providedProducts" : "...", "useInPlanningPenalty" : 12345.0, "maximumDistance" : 12345, "maximumVisits" : 12345, "mobileLogin" : "...", "useAllCapacities" : true, "globalCapacity" : 12345.0, "additionalCostOrderCustomDataName" : "...", "additionalCostOperator" : "SUM", "additionalCosts" : [ { }, { } ], "openTimeStart" : true, "openDistanceStart" : true, "openTimeStop" : true, "openDistanceStop" : true, "tomTomWebFleetEnabled" : true, "tomTomWebFleetIdentifier" : "...", "vehicleCode" : "...", "fuelCode" : "..." } ], "orders" : [ { "allSkillsRequired" : true, "assignResources" : [ "...", "..." ], "courierPenalty" : 12345.0, "customDataMap" : { "property1" : "...", "property2" : "..." }, "delayPenaltyPerHour" : 12345.0, "excludeResources" : [ "...", "..." ], "fixedVisitDuration" : "...", "frequency" : "...", "id" : "...", "minDuration" : "...", "minPartDuration" : "...", "punctuality" : 12345, "quantities" : [ 12345.0, 12345.0 ], "requiredSkills" : [ "...", "..." ], "resourceCompatibility" : 12345.0, "sequenceNumber" : 12345, "timeWindows" : [ { }, { } ], "travelTimeModifier" : { }, "type" : 12345, "unloadingDurationPerUnit" : "...", "x" : 12345.0, "y" : 12345.0, "active" : true, "wholeVisitInTimeWindow" : true, "label" : "...", "evaluationInfos" : { }, "possibleVisitDaysList" : [ "...", "..." ], "tsOrderMaximumSpacing" : 12345, "tsOrderMinimumSpacing" : 12345, "tsOrderLastVisit" : 12345, "customerId" : "...", "email" : "...", "phone" : "...", "tsOrderBefore" : "...", "tsOrderBeforeMaxTimeSpacing" : "...", "tsOrderBeforeMinTimeSpacing" : "...", "getNotifications" : true, "tsOrderFixed" : true }, { "allSkillsRequired" : true, "assignResources" : [ "...", "..." ], "courierPenalty" : 12345.0, "customDataMap" : { "property1" : "...", "property2" : "..." }, "delayPenaltyPerHour" : 12345.0, "excludeResources" : [ "...", "..." ], "fixedVisitDuration" : "...", "frequency" : "...", "id" : "...", "minDuration" : "...", "minPartDuration" : "...", "punctuality" : 12345, "quantities" : [ 12345.0, 12345.0 ], "requiredSkills" : [ "...", "..." ], "resourceCompatibility" : 12345.0, "sequenceNumber" : 12345, "timeWindows" : [ { }, { } ], "travelTimeModifier" : { }, "type" : 12345, "unloadingDurationPerUnit" : "...", "x" : 12345.0, "y" : 12345.0, "active" : true, "wholeVisitInTimeWindow" : true, "label" : "...", "evaluationInfos" : { }, "possibleVisitDaysList" : [ "...", "..." ], "tsOrderMaximumSpacing" : 12345, "tsOrderMinimumSpacing" : 12345, "tsOrderLastVisit" : 12345, "customerId" : "...", "email" : "...", "phone" : "...", "tsOrderBefore" : "...", "tsOrderBeforeMaxTimeSpacing" : "...", "tsOrderBeforeMinTimeSpacing" : "...", "getNotifications" : true, "tsOrderFixed" : true } ], "nbQuantities" : 12345, "nbCapacities" : 12345, "nbTimeWindows" : 12345, "nbExtraTravelPenalties" : 12345, "depotProperties" : [ "...", "..." ], "resourceProperties" : [ "...", "..." ], "orderProperties" : [ "...", "..." ], "options" : { "evaluation" : true, "startFromEvaluationInfo" : true, "maxOptimDuration" : "...", "reloadDuration" : "...", "noReload" : true, "distanceType" : "METERS", "teamId" : "...", "sendResultToWebhook" : "ORDERS", "countVisitCostOnceIfSameLocation" : true, "countDepotsInDeliveryCost" : "NONE", "excludeVisitCostIfMaxAdditionalCost" : true, "routingMethod" : "DISTANCE", "allowToll" : true, "allowTunnel" : true, "allowBridge" : true, "vehicleCode" : "...", "fuelCode" : "...", "speedPattern" : "...", "useForbiddenTransitAreas" : true, "useOTSolver" : true, "balanceType" : "HOURS", "balanceValue" : 12345 } }, "message" : "...", "status" : "ERROR" } }
GET /toursolver/status
Description Get optimization status.
This service allows to know the status of an optimization.
Type | Name | Description | Schema | Default |
---|---|---|---|---|
Query |
taskId |
the id of optimization task, as returned by the optimize service |
string |
-
application/xml
-
application/json
-
text/xml
Example HTTP response =.Response 200
{ "application/json" : { "optimizeStatus" : "geocoding", "startTime" : 12345, "currentCo2" : 12345.0, "currentCost" : 12345, "currentCourierCost" : 12345, "currentDeliveredQuantity" : 12345.0, "currentDeliveryCost" : 12345, "currentDriveCost" : 12345, "currentDriveDistance" : 12345, "currentDriveTime" : 12345, "currentFixedCost" : 12345, "currentLateTime" : 12345, "currentNightsCost" : 12345, "currentOverWorkCost" : 12345, "currentOverWorkTime" : 12345, "currentPickUpQuantity" : 12345.0, "currentRestTime" : 12345, "currentUnplannedVisits" : 12345, "currentWaitTime" : 12345, "currentWorkCost" : 12345, "currentWorkTime" : 12345, "initialCo2" : 12345.0, "initialCost" : 12345, "initialCourierCost" : 12345, "initialDeliveredQuantity" : 12345.0, "initialDeliveryCost" : 12345, "initialDriveCost" : 12345, "initialDriveDistance" : 12345, "initialDriveTime" : 12345, "initialFixedCost" : 12345, "initialLateTime" : 12345, "initialNightsCost" : 12345, "initialOverWorkCost" : 12345, "initialOverWorkTime" : 12345, "initialPickUpQuantity" : 12345.0, "initialRestTime" : 12345, "initialUnplannedVisits" : 12345, "initialWaitTime" : 12345, "initialWorkCost" : 12345, "initialWorkTime" : 12345, "mileageChartRemainingTime" : 12345, "initialOpenTourNumber" : 12345, "currentOpenTourNumber" : 12345, "subOptimNb" : 12345, "subOptimWaitingNb" : 12345, "subOptimRunningNb" : 12345, "subOptimFinishedNb" : 12345, "subOptimErrorNb" : 12345, "subOptimAbortedNb" : 12345, "simulationId" : "...", "currentVisitsNb" : 12345, "initialPlannedVisits" : 12345, "currentPlannedVisits" : 12345, "message" : "...", "status" : "ERROR" } }
POST /toursolver/stop
Description Stop optimization.
Interrupt optimization task.
This stop is asynchronous. You should use the related status function to know when the action is truly stopped.
Type | Name | Description | Schema | Default |
---|---|---|---|---|
Query |
taskId |
the id of optimization task, as returned by the optimize service |
string |
-
application/xml
-
application/json
-
text/xml
Example HTTP response =.Response 201
{ "application/json" : { "firstStopAsked" : 12345, "message" : "...", "status" : "OK" } }
GET /toursolver/toursResult
Description Get optimization result organized by tours.
Get the result of planning optimization organized by tours (one tour per resource per day). Status of the optimization must be terminated.
Type | Name | Description | Schema | Default |
---|---|---|---|---|
Query |
taskId |
the id of optimization task, as returned by the optimize service |
string |
-
application/xml
-
application/json
-
text/xml
Example HTTP response =.Response 200
{ "application/json" : { "taskId" : "...", "tours" : [ { "dayId" : "...", "resourceId" : "...", "travelDistance" : 12345, "travelDuration" : "...", "resourceCapacities" : [ 12345.0, 12345.0 ], "usedCapacities" : [ 12345.0, 12345.0 ], "deliveryCost" : 12345.0, "plannedOrders" : [ { "dayId" : "...", "stopPosition" : 12345, "stopY" : 12345.0, "stopX" : 12345.0, "stopId" : "...", "stopType" : 12345, "stopDriveTime" : "...", "stopStartTime" : "...", "stopDuration" : "...", "stopStatus" : 12345, "stopDriveDistance" : 12345, "stopElapsedDistance" : 12345, "resourceId" : "..." }, { "dayId" : "...", "stopPosition" : 12345, "stopY" : 12345.0, "stopX" : 12345.0, "stopId" : "...", "stopType" : 12345, "stopDriveTime" : "...", "stopStartTime" : "...", "stopDuration" : "...", "stopStatus" : 12345, "stopDriveDistance" : 12345, "stopElapsedDistance" : 12345, "resourceId" : "..." } ], "additionalCost" : 12345.0, "totalCost" : 12345.0, "reloadNb" : 12345 }, { "dayId" : "...", "resourceId" : "...", "travelDistance" : 12345, "travelDuration" : "...", "resourceCapacities" : [ 12345.0, 12345.0 ], "usedCapacities" : [ 12345.0, 12345.0 ], "deliveryCost" : 12345.0, "plannedOrders" : [ { "dayId" : "...", "stopPosition" : 12345, "stopY" : 12345.0, "stopX" : 12345.0, "stopId" : "...", "stopType" : 12345, "stopDriveTime" : "...", "stopStartTime" : "...", "stopDuration" : "...", "stopStatus" : 12345, "stopDriveDistance" : 12345, "stopElapsedDistance" : 12345, "resourceId" : "..." }, { "dayId" : "...", "stopPosition" : 12345, "stopY" : 12345.0, "stopX" : 12345.0, "stopId" : "...", "stopType" : 12345, "stopDriveTime" : "...", "stopStartTime" : "...", "stopDuration" : "...", "stopStatus" : 12345, "stopDriveDistance" : 12345, "stopElapsedDistance" : 12345, "resourceId" : "..." } ], "additionalCost" : 12345.0, "totalCost" : 12345.0, "reloadNb" : 12345 } ], "warnings" : [ { "objectType" : "...", "id" : "...", "constraint" : 12345, "value" : "...", "message" : "...", "messageId" : 12345, "i18nMessageCode" : "...", "constraintName" : "..." }, { "objectType" : "...", "id" : "...", "constraint" : 12345, "value" : "...", "message" : "...", "messageId" : 12345, "i18nMessageCode" : "...", "constraintName" : "..." } ], "unplannedOrders" : [ { "stopID" : "...", "reason" : "..." }, { "stopID" : "...", "reason" : "..." } ], "message" : "...", "status" : "ERROR" } }
You can easily use the TsCloud API using only javascript. It is very easy to perform ajax requests with any popular javascript framework. We will show in this chapter how to do it with JQuery.
First of all, you will need to include Jquery and tsCloudApi.js :
<html> <head> <title>TsCloud Api Tester</title> <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.12.2/jquery.min.js"></script> <script src="https://geoservices.geoconcept.com/ToursolverCloud/combo?toursolver/tsCloudApi.js"></script> </head> <body> ... </body> </html>
![]() |
Warning |
---|---|
Depending on your geographical area, the ToursolverCloud url may be different. |
You will then use de tsCloudApi object to communicate with TsCloud servers. Before sending any request, you must initialize the object with your api key :
<script> var myApiKey = "this is a fake key"; tsCloudApi.init(myApiKey); </script>
To start an optimization, you will have use the optimize method of the tsCloudApi object :
<script> var myApiKey = "this is a fake key"; tsCloudApi.init(myApiKey); tsCloudApi.optimize(optimRequest,startOptimSuccessHandler,errorHandler); </script>
tsCloudApi performs asynchronous ajax requests. Therefore, you have to implement handler functions that will be called when the response will be available (startOptimSuccessHandler and errorHandler in the above example). optimRequest is the object containing the list of depots (optional), the list of resources, the list of orders and the optimization options (please refer to the definitions chapter for more details).
Here is a minimal example with one resource and two orders :
<script> var optimRequest = { "depots": [], "resources": [{ "x": 2.33683, "y": 48.86255, "id": "Robert", "workStartTime": "08:00", "workEndTime": "18:00", "lunch": { "start": "12:00", "end": "14:00", "duration": "01:00", }, "workingDays": "1-5", "capacities": [1000.0], "workPenalty": 20.0, "overtimePenalties": [0.0], "travelPenalty": 2.0, }], "orders": [{ "id": "ORDER-1", "label": "HOSPITAL", "quantities": [2.0], "fixedVisitDuration": "00:30", "timeWindows": [{ "beginTime": "08:00", "endTime": "10:00" }], "x": 2.348433, "y": 48.853661 }, { "id": "ORDER-2", "label": "EMERGENCIES", "quantities": [2.0], "fixedVisitDuration": "00:25", "timeWindows": [{ "beginTime": "10:00", "endTime": "12:00" }], "x": 2.347802, "y": 48.854687 }], , "options": { "vehicleCode": "car", "stopTime": "00:01", "stopTimeWithoutImprovement": "00:01", "maxOptimDuration": "00:01", "stopCondition": 1, "reloadDuration": "00:45" }, "countryCode":"FR" }; </script>
Here is how you could write your error handler :
<script> function errorHandler(jqxhr,status,errorThrown) { if (jqxhr.status == 403) { console.log("Bad key code ?"); } else if (jqxhr.status == 429) { console.log("oups, slow down please : " + jqxhr.statusText); } else if (jqxhr.status != 200) { console.log("sorry, an error occured : " + jqxhr.statusText); try { if (jqxhr.responseText) { var resp = JSON.parse(jqxhr.responseText); if (resp.message) { console.log(resp.message); } } } catch (e) { console.log("could not find details about the error"); } } } </script>
If your api key is not valid, you will get a 403 http code. As explained in authentication chapter, you may received a 429 http code if you send to many requests in a short time. If you misspelled an object attribut or for any other technical problem, you may receive a 500 http code.
Here is how you could write your success handler, which must retrieve the taskId and start the status polling process that we will detail in the next section :
<script> var taskId = null; function startOptimSuccessHandler(data,status,xhr) { if (data.status == "OK") { taskId = data.taskId; console.log("optim launched. taskId is " + taskId); getStatus(); } else { console.log(data.message); } } </script>
During the optimization process, you will be able to follow the cost evolution and the state of the optimization by calling the getStatus method of the tsCloudApi object :
<script> tsCloudApi.getStatus(taskId,getStatusSuccessHandler,errorHandler); </script>
You can use the same errorHandler function we used for the optimization request. Your getStatusSuccessHandler should mainly check the optimization state, but it can be used to track the costs evolution. It is quite easy to build graphs to show this evolution. Here is an example using canvasjs. First of all, you must include canvasjs :
<html> <head> <title>TsCloud Api Tester</title> <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.12.2/jquery.min.js"></script> <script src="https://cdnjs.cloudflare.com/ajax/libs/canvasjs/1.7.0/canvasjs.min.js"></script> <script src="https://geoservices.geoconcept.com/ToursolverCloud/combo?toursolver/tsCloudApi.js"></script> </head> <body> ... </body> </html>
Then, here is an example of getStatus command called every second, with the success handler used to build graphs, and to trigger the result download (that we will detail in a further section) :
<script> var getStatusTimeout = null; var graphIndex; var graphCost = null; var graphDist = null; function getStatus() { if (getStatusTimeout != null) { clearTimeout(getStatusTimeout); } getStatusTimeout = setTimeout(function() { tsCloudApi.getStatus(taskId,getStatusSuccessHandler,errorHandler); },1000); } function appendGraphData(data) { if (graphCost == null) { graphIndex = 0; var options = { title: { text: "Cost evolution" }, animationEnabled: true, data: [ { type: "spline", //change it to line, area, column, pie, etc dataPoints: [ { x: graphIndex, y: data.currentCost } ] } ] }; graphCost = new CanvasJS.Chart("chartContainerCost",options); options = { title: { text: "Distance evolution" }, animationEnabled: true, data: [ { type: "spline", //change it to line, area, column, pie, etc dataPoints: [ { x: graphIndex, y: data.currentDriveDistance / 1000 } ] } ] }; graphDist = new CanvasJS.Chart("chartContainerDist",options); } else { graphIndex++; graphCost.options.data[0].dataPoints.push({ x: graphIndex, y: data.currentCost }); graphDist.options.data[0].dataPoints.push({ x: graphIndex, y: data.currentDriveDistance/1000 }); } graphCost.render(); graphDist.render(); } function getStatusSuccessHandler(data,status,xhr) { if (data.optimizeStatus == "ERROR") { console.log("sorry, an error occured"); } else if (data.optimizeStatus == "TERMINATED") { console.log("optimization done"); setTimeout("getResult()",10); } else { if (data.status == "OK") { console.log(data.optimizeStatus + " | current cost : " + data.currentCost + " | current distance : " + data.currentDriveDistance); if (data.optimizeStatus == "RUNNING") { appendGraphData(data); } } else { console.log("sorry, an error occured : " + data.message); } getStatus(); } } </script>
Even if you must specify a maximum optimization time in the options objects sent in the optimization command, you can stop an optimization at any time. You can do this easily using the stop method of the tsCloudApi object :
<script> tsCloudApi.stop(taskId,stopSuccessHandler,errorHandler); </script>
Stopping an optimization may take a few seconds and when stopSuccessHandler is called, it only means that your stopping request as been aknowleged. Therefore, you still have to call the getStatus method until the status says that the optimization is terminated.
<script> function stopSuccessHandler(data,status,xhr) { if (data.optimizeStatus == "ERROR") { console.log("sorry, an error occured"); } else { getStatus(); } } </script>
Here we use the getStatus function detailed in the above section.
Once your optimization is terminated, you can retrieve the result using the getResult method of the tsCloudApi object :
<script> function getResult() { tsCloudApi.getResult(taskId,showResult,errorHandler); } </script>
The result will contain the resource and time assignment for each planned order, the list of unplanned orders and a list of warnings.
<script> var lastResult; function showResult(data,status,xhr) { if (data.status == "OK") { lastResult = data; //let's store the result for later ... displayResult(data); } else { appendTrace("sorry, an error occured : " + data.message); } } function displayResult(data) { $('#resultStats').append("<p>nb of unplanned orders : " + data.unplannedOrders.length+"</p>"); if (data.warnings && data.warnings.length > 0) { for (var i=0;i<data.warnings.length;i++) { $('#resultStats').append("<p>warning on " + data.warnings[i].id + " : " + data.warnings[i].message + " (" + data.warnings[i].value + ")"+"</p>"); } } var order = null; for (var i=0;i<data.plannedOrders.length;i++) { order = data.plannedOrders[i]; $('#resultPlanning').append("<p>order " + order.stopId + " as been planned on resource " + order.resourceId + " on day " + order.dayId + " at " + order.stopStartTime +"</p>"); } } </script>
You can aslo export your optimization result to operational planning so that mobile resources could browse it on the field through a mobile app. Note that you must have previously created your mobile identifiers through TsCloud app. If you are trying to export to a period that already contains data, you will get an error and have to force the export, which will erase previous data first.
<script> function doExportToOperational(taskId,exportStartDate,force) { var operationalExportParams = { resourceMapping : [ { id:"Robert", operationalId:"robert@mycompany.com" } ], startDate : (exportStartDate)?exportStartDate:new Date(), force : force, taskId : taskId }; tsCloudApi.exportToOperationalPlanning(operationalExportParams,showExportResult,errorHandler); } </script>
Once your optimization is finished, you can use Toursolver to show the result. To to this, you will have to retrieve a temporary login token and then open TsCloud in an iframe with this token and the simulationId found in the optimization result.
You can choose to show the full Toursolver UI, or only the result page just passing standalone=true as a parameter of the url.
<iframe id="integrationFrame" style="width:100%;height:800px;border:none;"></iframe> <script> var doStandaloneIntegration = false; var lastResult; //we assume here that you have stored the result obtained earlier in this var function startIntegration(standaloneIntegration) { doStandaloneIntegration = standaloneIntegration; //Here we retrieve a temporary token tsCloudApi.getGatewayToken(startIntegrationHandleFunc, errorHandler); } function startIntegrationHandleFunc(data,status,xhr) { //We have received our token, let's build the url to display the simulation result let url = 'https://app.geoconcept.com/ToursolverCloud/ts/login?'; url += 'token='+data.token; url += '&simulationId='+ lastResult.simulationId; if (doStandaloneIntegration) { url += '&standalone=true'; } //Here we will set the src of an existing iframe (having id='integrationFrame') to display Toursolver result page in it $('#integrationFrame').attr('src', url) } </script>
If you can also specify the day and the resource to be shown :
https://app.geoconcept.com/ToursolverCloud/ts/login?token=xxx&standalone=true&day=1&resource=Robert
By default, the standalone mode also hides the resources/days selector above the orders list. You can get it back by setting the showSelector parameter :
With new result page only, you can open a result in read only mode, all actions are disabled in this mode :
For compatibility, you can still use the old integration url (https://geoservices.geoconcept.com/ToursolverCloud), in this case, use tsCloudApi.getLoginToken instead of tsCloudApi.getGatewayToken, but you should migrate to the new url.
In the following sections, you will find some client libraries for different languages and tips that will help you to use our API. If you do not find a client for your favorite language, you will probably be able to generate your own one from our wsdl or wadl.
We do not provide C# client library but you can easily build one from the wdsl using the ServiceModel Metadata Utility Tool (Svcutil.exe) or Visual Studio’s Add Service Reference Dialog.
C# Resource Example :
//read a resource from a REST url Uri uri = new Uri(...); XmlSerializer s = new XmlSerializer( typeof( byte[] ) ); //Create the request object WebRequest req = WebRequest.Create(uri); WebResponse resp = req.GetResponse(); Stream stream = resp.GetResponseStream(); TextReader r = new StreamReader( stream ); byte[] result = (byte[]) s.Deserialize( r ); //handle the result as needed...
The Java client-side library is used to provide the set of Java objects that can be serialized to/from XML using JAXB. This is useful for accessing the resources that are published by this application.
Download toursolver-xml-client.jar
Resources Example (Raw JAXB) :
java.net.URL url = new java.net.URL(baseURL + "/toursolver/optimize"); JAXBContext context = JAXBContext.newInstance( byte[].class, byte[].class ); java.net.URLConnection connection = url.openConnection(); connection.setDoOutput(true); connection.connect(); Unmarshaller unmarshaller = context.createUnmarshaller(); Marshaller marshaller = context.createMarshaller(); marshaller.marshal(optimizeRequest, connection.getOutputStream()); OptimizeResult result = (OptimizeResult) unmarshaller.unmarshal( connection.getInputStream() ); //handle the result as needed...
Resources Example (Jersey client) :
javax.ws.rs.client.Client client = javax.ws.rs.client.ClientBuilder.newClient(); OptimizeResult result = client.target(baseUrl + "/toursolver/optimize") .post(javax.ws.rs.client.Entity.entity(optimizeRequest, "application/xml"), OptimizeResult.class); //handle the result as needed...
The JavaScript client-side library defines classes that can be (de)serialized to/from JSON. This is useful for accessing the resources that are published by this application, but only those that produce a JSON representation of their resources (content type "application/json").
he library uses ES6 class syntax which has limited support. See MDN and the ES6 Compatibility Table for more details.
The library contains a UMD loader which supports AMD, CommonJS and browser globals. The browser global variable name for this library is "javascriptClient".
Download toursolver-js.zip
JavaScript Example :
/read the resource in JSON: var json = JSON.parse(jsonString); //create an object var object = new Object(json); //retreive the json again var newJson = object.toJSON(); //serialize the json var newJsonString = JSON.stringify(newJson);
The PHP JSON client-side library defines the PHP classes that can be (de)serialized to/from JSON. This is useful for accessing the resources that are published by this application, but only those that produce a JSON representation of their resources (content type "application/json").
This library requires the json_encode function which was included in PHP versions 5.2.0+.
Download toursolver-php.zip
PHP JSON Example :
//read the resource in JSON: $json = ...; //read the json as an array. $parsed = json_decode($json, true); //read the json array as the object $result = new Object($parsed); //open a writer for the json $json = $result->toJson();
The PHP client-side library defines the PHP classes that can be (de)serialized to/from XML. This is useful for accessing the resources that are published by this application, but only those that produce a XML representation of their resources.
This library leverages the XMLReader and XMLWriter tools that were included in PHP versions 5.1.0+.
Download toursolver-php.zip
PHP XML Example :
//read the resource in XML form: $xml = ...; $reader = new \XMLReader(); if (!$reader->open($xml)) { throw new \Exception('Unable to open ' . $xml); } $result = new Object($reader); //open a writer for the xml $out = ...; $writer = new \XMLWriter(); $writer->openUri($out); $writer->startDocument(); $writer->setIndent(4); $result->toXml($writer); $writer->flush();
Name | Description | Schema |
---|---|---|
id |
Example : |
string |
language |
Example : |
string |
orders |
< json_TSOrder > array |
Name | Description | Schema |
---|---|---|
message |
Example : |
string |
status |
Example : |
string |
generic result of service
Polymorphism : Composition
Name | Description | Schema |
---|---|---|
depots |
List of depots |
< json_TSDepot > array |
message |
error message |
string |
status |
response status, OK or ERROR |
Name | Description | Schema |
---|---|---|
feature |
||
payload |
object |
generic result of service
Polymorphism : Composition
Name | Description | Schema |
---|---|---|
lastKnownPosition |
List of positions |
< json_OperationalLastKnownPosition > array |
message |
error message |
string |
operationalOrderAchievements |
List of orders |
< json_OperationalOrderAchievement > array |
status |
response status, OK or ERROR |
<p>Classe Java pour GPSStatus.
<p>Le fragment de sch??ma suivant indique le contenu attendu figurant dans cette classe. <p> <pre> <simpleType name="GPSStatus"> <enumeration value="0"/> <enumeration value="1"/> <enumeration value="2"/> </restriction> </simpleType> </pre>
Type : enum (0, 1, 2)
Name | Description | Schema |
---|---|---|
address |
Example : |
string |
addressComplement |
Example : |
string |
city |
Example : |
string |
country |
Example : |
string |
geocodeAddressLine |
Example : |
string |
geocodeCity |
Example : |
string |
geocodePostalCode |
Example : |
string |
geocodeType |
number |
|
postcode |
Example : |
string |
region |
Example : |
string |
score |
number |
Result of the optimize service
Polymorphism : Composition
Name | Description | Schema |
---|---|---|
message |
error message |
string |
status |
response status, OK or ERROR |
|
token |
the token string |
string |
validUntil |
The token validity end date |
number |
Operational planning export parameters
Name | Description | Schema |
---|---|---|
dayNums |
< number > array |
|
force |
if true, any existing operational planning will be replaced if false and if optimization period overlaps any existing operational planning, export will fail. |
boolean |
resourceMapping |
List of MobileResourceMapping defining relation between resource identifier in optimize request and real mobile resource identifier |
< json_OperationalResourceMapping > array |
startDate |
real date corresponding to day 1 of optimize request data |
number |
taskId |
Task identifier. Must point to a completed optimization. |
string |
Polymorphism : Composition
Name | Description | Schema |
---|---|---|
accuracy |
GPS positioning accuracy (radius in meters) |
number |
batteryLevel |
Battery level of the device |
number |
date |
last position recording date |
number |
gpsStatus |
GPS status of the device |
|
id |
Example : |
string |
lat |
Latitude |
number |
lon |
Longitude |
number |
privateLife |
Private life status in Mobile App. If true, it means that mobile App is currently in Private life mode, therefore this position is the last known position before the Private life switch. |
boolean |
Polymorphism : Composition
Name | Description | Schema |
---|---|---|
achievementComment |
Achievement comment |
string |
achievementEnd |
Achievement end date and time |
number |
achievementEndLat |
Achievement end latitude |
number |
achievementEndLon |
Achievement end longitude |
number |
achievementStart |
Achievement start date and time |
number |
achievementStartLat |
Achievement start latitude |
number |
achievementStartLon |
Achievement start longitude |
number |
apprauchSmsId |
Example : |
string |
apprauchSmsStatus |
Example : |
string |
data |
fulfillment form data |
< string, string > map |
date |
Planning day |
number |
end |
Planned end date and time |
number |
feedbackSmsId |
Example : |
string |
feedbackSmsStatus |
Example : |
string |
geocode |
||
id |
Example : |
string |
lastSynchroStatusChange |
Last change from mobile app |
number |
lat |
Latitude |
number |
lon |
Longitude |
number |
operationalResourceId |
Mobile resource identifier (mobile app login) |
string |
order |
Original order |
|
pictures |
List of picture relative urls. Url root for pictures is https://geoservices.geoconcept.com/ToursolverCloud/api/rest/otmobile/pictures/ |
< string > array |
plannedOrder |
Planned order |
|
signaturePicture |
Signature, as a picture relative URL (a flavor of the reference signatureSvg) Is bound and synced from the signaturesSvg field. Is a relative URL, as
also done for the pictures field (see its documentation for details). |
string |
signatureSvg |
Signature svg |
string |
simulationDayId |
day containing this order in the simulation used to fill the fulfillment
planning |
string |
simulationId |
identifier of the simulation used to fill the fulfillment planning |
string |
start |
Planned start date and time |
number |
status |
fulfillment status |
|
synchroStatus |
Sync status |
|
timeWindowEnd |
number |
|
timeWindowSmsId |
Example : |
string |
timeWindowSmsStatus |
Example : |
string |
timeWindowStart |
number |
|
type |
Event type |
Type : enum (CANDIDATE, FIXED, ACCEPTED, REFUSED, STARTED, FINISHED, CANCELLED, PAUSED, RESUMED, UNKNOWN)
Type : enum (MISSION, RESTBREAK, LUNCHBREAK, WAITBREAK, RELOADBREAK, START, END, ENDBEFORENIGHT, STARTAFTERNIGHT, BRIEFING, DEBRIEFING, UNKNOWN)
The mobile resource mapping links the resource identifier used in optimized data and the mobile resource identifier used for operational planning export
Name | Description | Schema |
---|---|---|
id |
resource identifier |
string |
operationalId |
Mobile identifier |
string |
Result of an optimization task.
Polymorphism : Composition
Name | Description | Schema |
---|---|---|
message |
error message |
string |
plannedOrders |
the planned stops |
< json_TSPlanned > array |
simulationId |
Id of the simulation associated to this task |
string |
status |
response status, OK or ERROR |
|
taskId |
the id of the optimization task (usefull if result is automatically sent through a webhook). |
string |
unplannedOrders |
the orders which has not been planned because: <li>it was sent by an other mail service <li>it was not scheduled by any resource. |
< json_TSUnplanned > array |
warnings |
the list of warning messages (and associated error codes) about possible Orders and Resources elements constraints misconfiguration. |
< json_TSWarning > array |
Result of status request
Polymorphism : Composition
Name | Description | Schema |
---|---|---|
currentCo2 |
Remaining Kg CO2 of the current solution |
number |
currentCost |
Cost of the current solution |
number |
currentCourierCost |
Courier cost of the current solution |
number |
currentDeliveredQuantity |
Total quantity delivered of the current solution |
number |
currentDeliveryCost |
Delivery cost of the current solution |
number |
currentDriveCost |
Drive cost of the current solution |
number |
currentDriveDistance |
Drive distance of the current solution |
number |
currentDriveTime |
Drive time in seconds of the current solution |
number |
currentFixedCost |
Fixed cost of the current solution |
number |
currentLateTime |
Late time in seconds of the current solution |
number |
currentNightsCost |
Nights cost of the current solution |
number |
currentOpenTourNumber |
initial number of open tours (tours with at least one visit) |
number |
currentOverWorkCost |
Overwork cost of the current solution |
number |
currentOverWorkTime |
Over work time in seconds of the current solution |
number |
currentPickUpQuantity |
Total quantity picked-up of the current solution |
number |
currentPlannedVisits |
Number of planned visits of the current solution (new engine only) |
number |
currentRestTime |
Rest time in seconds of the current solution |
number |
currentUnplannedVisits |
Number of visits unplanned or delivered by a courier of the current solution |
number |
currentVisitsNb |
number |
|
currentWaitTime |
Wait time in seconds of the current solution |
number |
currentWorkCost |
Work cost of the current solution |
number |
currentWorkTime |
Work time in seconds of the current solution |
number |
initialCo2 |
Remaining Kg CO2 of the initial solution |
number |
initialCost |
Cost of the initial solution |
number |
initialCourierCost |
Courier cost of the initial solution |
number |
initialDeliveredQuantity |
Total quantity delivered of the initial solution |
number |
initialDeliveryCost |
Delivery cost of the initial solution |
number |
initialDriveCost |
Drive cost of the initial solution |
number |
initialDriveDistance |
Drive distance of the initial solution |
number |
initialDriveTime |
Drive time in seconds of the initial solution |
number |
initialFixedCost |
Fixed cost of the initial solution |
number |
initialLateTime |
Late time in seconds of the initial solution |
number |
initialNightsCost |
Nights cost of the initial solution |
number |
initialOpenTourNumber |
initial number of open tours (tours with at least one visit) |
number |
initialOverWorkCost |
Overwork cost of the initial solution |
number |
initialOverWorkTime |
Over work time in seconds of the initial solution |
number |
initialPickUpQuantity |
Total quantity picked-up of the initial solution |
number |
initialPlannedVisits |
Number of planned visits of the initial solution (new engine only) |
number |
initialRestTime |
Rest time in seconds of the initial solution |
number |
initialUnplannedVisits |
Number of visits unplanned or delivered by a courier of the initial solution |
number |
initialWaitTime |
Wait time in seconds of the initial solution |
number |
initialWorkCost |
Work cost of the initial solution |
number |
initialWorkTime |
Work time in seconds of the current solution |
number |
message |
error message |
string |
mileageChartRemainingTime |
Mileage and travel time matrix computing remaining time. This information may not be available depending on the geographical area. |
number |
optimizeStatus |
Current status of the optimization process |
|
simulationId |
Id of the simulation associated to this task |
string |
startTime |
Start time of the optimization |
number |
status |
response status, OK or ERROR |
|
subOptimAbortedNb |
Number of sub-optimizations in aborted state |
number |
subOptimErrorNb |
Number of sub-optimizations in error state |
number |
subOptimFinishedNb |
Number of sub-optimizations in finished state |
number |
subOptimNb |
Number of sub-optimizations created (after pre-sectorization) |
number |
subOptimRunningNb |
Number of sub-optimizations in running state |
number |
subOptimWaitingNb |
Number of sub-optimizations in waiting state |
number |
Result of status request
Polymorphism : Composition
Name | Description | Schema |
---|---|---|
firstStopAsked |
First stop demand stamp |
number |
message |
error message |
string |
status |
response status, OK or ERROR |
Result of an optimization task.
Polymorphism : Composition
Name | Description | Schema |
---|---|---|
message |
error message |
string |
status |
response status, OK or ERROR |
|
taskId |
the id of the optimization task (usefull if result is automatically sent through a webhook). |
string |
tours |
List of tours (one tour per resource per day) |
< json_TSTour > array |
unplannedOrders |
the orders which has not been planned because: <li>it was sent by an other mail service <li>it was not scheduled by any resource. |
< json_TSUnplanned > array |
warnings |
the list of warning messages (and associated error codes) about possible Orders and Resources elements constraints misconfiguration. |
< json_TSWarning > array |
Optimization request
Name | Description | Schema |
---|---|---|
beginDate |
This date will be used if you try to export the optimization result through TsCloud GUI. Format : YYYY-MM-DD Default : day+1. |
number |
countryCode |
Main country code used to route the optimization to the good optimization
server farm. |
string |
depots |
list of depots (for reloading or starting tours) |
< json_TSDepot > array |
language |
Language to use for message localization |
string |
options |
the optimize task options |
|
orders |
list of orders (visits to do) |
< json_TSOrder > array |
organization |
In multi-user content, you generally create various organizations that allows to define who sees what. If you set the organization here, only users that can see this organization will see the result of this optimization in the UI. Note that if you specified a teamId instead of sending the resources in the optimization data, the organization will be guessed from the team. If no organization is set, all users will see the result. |
string |
resources |
collection of resources, the elements which will perform deliveries, pick-ups, commercial visit, etc. |
< json_TSResource > array |
simulationName |
Simulation name Optional : generated automatically if not provided |
string |
userLogin |
In multi-user content, you can specify a user login you. The simulation
will be owned by this user. By default, the owner of the simulation is
the default user of the account. |
string |
Result of the optimize service
Polymorphism : Composition
Name | Description | Schema |
---|---|---|
message |
error message |
string |
status |
response status, OK or ERROR |
|
taskId |
the id of the optimization task that was launched |
string |
Type : enum (undefined, waiting, geocoding, mileageChartBuilding, running, aborted, terminated, error, sectorizationWaiting, sectorizationRunning, sectorizationFinished, sectorizationAborted)
generic result of service
Polymorphism : Composition
Name | Description | Schema |
---|---|---|
message |
error message |
string |
resources |
List of resources |
< json_TSResource > array |
status |
response status, OK or ERROR |
generic result of service
Polymorphism : Composition
Name | Description | Schema |
---|---|---|
message |
error message |
string |
simulation |
||
status |
response status, OK or ERROR |
Name | Description | Schema |
---|---|---|
type |
TSOrder type (stored in a custom data) |
string |
value |
Cost for this type |
number |
The Depots object stores depots data. They are composed of X,Y coordinates, identity tags and a set of constraints.
If you want to specify depot locations or allow a resource to reload at several depots, use the Depots object to add and configure your depot data. The Depots object contains zero or more elements. If it contains no element, the base location of each resource acts as a depot location. Once a depot is associated with a resource its base location is no longer used as a depot location.
Polymorphism : Composition
Name | Description | Schema |
---|---|---|
allProductsRequired |
Indicates whether a resource must provide all required products or one at least. Set it to True to indicate that a resource must provide all the depot required products. Set it to False to indicate that a resource must provide at least one of the depot required products. Type : boolean Default : True |
boolean |
availability |
Indicates whether a depot is included in the planning process or not. This constraint enables you to easily modify your optimization problem configuration without having to add nor delete your original data. * Set it to True to include a depot element in the planning process. * Set it to False to ignore it: it will not be used in the planning. |
boolean |
deliveryQuantities |
The available quantities of products available at the depot. You can specify up to 24 quantities Type : float array |
< number > array |
excludeResources |
The list of resources excluded from the depot. Use this constraint to specify a list of resources that can not use the depot. Type : string array.
Default: Empty array: no resource is excluded from the depot |
string |
fixedLoadingDuration |
The fixed duration for a resource to load at depot. Use this constraint to specify how long takes any resource reload at the depot. You can specify an additional duration according to the quantity to reload, using loadingDurationPerUnit. Type : "hh:mm:ss", DateTime. Default : "00:00:00". Example : tsDepot fixedVisitDuration = "00:30:00" indicates that 30 minutes are
needed to load at the depot. tsDepot loadingDurationPerUnit = 120
indicates that 120 seconds are needed to load one unit. If the quantity to
reload is 8, for instance, the variable part is 120*8. 16 minutes are
required to load at the depot. Total load time = 30 minutes + 16 minutes
= 46 minutes accounted for this reload break. |
string |
id |
The unique identifier of the depot |
string |
loadingDurationPerUnit |
The time needed to load a unit of product. This constraint is added to the fixed part of the loading duration: it depends on the total quantity to load. Type : "hh:mm:ss", DateTime, Integer (number of seconds). Default : 0. |
string |
openingDaysList |
The depot days of opening, related to the nth depot time window. Use this constraint to specify the days of operation of a depot referring to a depot time window. It must be related to the tsResourceWorkDays constraint of the resources, as resources work days define the planning period. Depot may be opened on a 64-days long period max, from day 1 to day 64. Type : string value containing days separated with commas (like "1, 2, 5" or "4, 20/05/2010") or intervals (like "1-10", "2=>5" or "22/05/2010=>03/06/2010"). For day intervals, prefer the "=>" separator. 1 is the first day of the planning period, the corresponding date, if any, is defined by the oldest date, for all resources, in the tsResourceWorkDays constraint. No date in the depots days of opening description can precede the first day of the planning period defined by the resources (which is day 1). Default : 1=>64. Example : * Set it to "1" (or "14/05/2010) when a depot is opened on the first day of the planning period. Set it to "1, 2, 4, 5" (or "14/05/2010,15/05/2010,17/05/2010,18/05/2010") if depot may not be visited on the third day of a five-days planning period. * Set it to "1=>5" (or "14/05/2010=>18/05/2010") to define a 5-days long period during which the depot is opened. |
< string > array |
pickupQuantities |
The available space for a product available at the depot. You can specify up to 24 values. Type : float array |
< number > array |
priority |
Depot priority. Use this constraint to specify a priority on the depot. If two depots are nearby the system considers the one with the highest priority **Type : * integer |
number |
requiredProducts |
The list of the products a depots contains. Use this constraint when a depot must be affected to a specific kind of resource: these resources will have to provide the required required to be able to load at the depot. Type : string (as a list of products separated with commas). Default : none |
string |
resourceNames |
Lists the resources that can use the depot. Type : string array. Default : Empty array: no resource can use the depot. Example : Specify ["Vehicle 1","Vehicle 2"] to allow only the resources with
tags "Vehicle 1" and "Vehicle 2" to use the depot. |
string |
timeWindows |
The depot time windows. Use this constraint to specify a depot time window during which the depot is opened. A depot time window is defined by its start time, its end time and days of opening. The start time of a depot time window is the first instant when a resource can enter the depot. Its end time is the last instant when a resource can enter the depot (but it may leave it afterward). You can specify up to 4 depot time windows for each depot. Type : "hh:mm:ss", DateTime. Default : "00:00:00". |
< json_TSTimeWindow > array |
travelTimeModifier |
Indicates the value of the travel time modifier. When reaching a location situated in a large city, one may want to take into account driving difficulties, such as narrow streets and congestion. The travel time modifier enables to increase the travel times around a location. It is describes by three values. The value by which multiply the travel times around the location (tsDepotTravelTimeModifierValue), the portion of the travel time on which the modifier applies (tsDepotTravelTimeModifierLength) an offset to add to any travel duration leaving or reaching the location (tsDepotTravelTimeModifierOffSet). Example : * Set tsResource travelTimeModifierValue to 1.5, tsResource travelTimeModifierLength to 300 and tsResource travelTimeModifierOffSet to 60 for Resource 1 * Set tsDepot travelTimeModifierValue to 2, tsDepot travelTimeModifierLength to 420 and tsDepot travelTimeModifierOffSet to 0 for Depot 1 If the initial travel duration between Resource 1 and Depot 1 was 1000, one obtains a travel time 360 * 1.5 + 60 + 280 + 420 * 2 + 0 = 1660 Type : float, Default : 1 |
|
x |
longitude WGS84 of depot |
number |
y |
latitude WGS84 of depot |
number |
Name | Description | Schema |
---|---|---|
orderOriginalResourceId |
The identity of the resource which visits the customer when evaluating an existing planning. * Use this constraint when you want to evaluate an existing planning. * Use the orderOriginalVisitDay constraint to specify the working day when the visit must be planned. * Use the orderPosition constraint to specify the position of a visit in the tour. Type : string (storing a unique resource tag). Default: : not used |
string |
orderOriginalVisitDay |
Indicates the work day when the resource which visits the customer when evaluating an existing planning. * Use this constraint when you want to evaluate an existing planning. * Use the orderOriginalResourceID to specify the resource which visit the customer. * Use the orderPosition to specify the position of a visit in the tour. Type : integer between 1 and 64 or string representing a date. 1 is the first day of the planning period, the corresponding date, if any, is defined by the oldest date, for all resources, in the tsResourceWorkDays constraint. if the original visit day is in the date format, this date cannot precede the first day of the planning period defined by the resources (which is day 1). Default : not used if the tsOrderOriginalResourceIDis not used, 1 overwise |
string |
orderPosition |
The position of a customer in a resource tour. Use this constraint when you want to evaluate a tour. Type : integer. Default : not used |
number |
Options for optimization request
Name | Description | Schema |
---|---|---|
allowBridge |
Allow toll If false, all bridges will be avoided. Default : true. |
boolean |
allowToll |
Allow toll If false, all toll ways will be avoided. Default : true. |
boolean |
allowTunnel |
Allow toll If false, all tunnels will be avoided. Default : true. |
boolean |
balanceType |
Route plans balancing type * NONE : no balancing * ORDERS : balance the number of orders (to be used with balanceValue) * HOURS : balance the route plans duration * QUANTITY : balance the route plans delivered quantity Only available with OTSolver |
|
balanceValue |
Route plans balancing target (to be used with balanceType) Locked route plans are not considered. Only available with OTSolver |
number |
countDepotsInDeliveryCost |
Depot cost configuration for tour delivery cost Specifies how depots stops are counted in tour delivery cost (using PenaltyPerVisit defined on resources). Possible values are : * NONE : depots stops are not counted in tour delivery cost * ALL : each depot stop counts as one visit in tour delivery cost * ALLBUTFIRST : first depot stop is ignored but each following depot stop will count as one visit in tour delivery cost * FIRST : only first depot stop is counted in tour delivery cost Default : NONE. |
|
countVisitCostOnceIfSameLocation |
If true, PenalPerVisit will counted only once in tour delivery cost if several visits at the same location are planned consecutively. |
boolean |
distanceType |
Set the distance unit (meters, feet, km or miles), defaut is meters |
|
evaluation |
Enable this if you just want to evaluate (get cost, distances, etc) a set of tours. Therefore, you must fill the evaluationInfos objects in orders Default : false. (see TSEvaluationInfos) |
boolean |
excludeVisitCostIfMaxAdditionalCost |
Exclude visit delivery cost for visits having the maximum additional cost |
boolean |
fuelCode |
Vehicles fuel type. Possible values are : * diesel * undefined * unleaded |
string |
maxOptimDuration |
maximum optimization time. Default is one minute. Type : Time ("hh:mm" or "hh:mm:ss") or Integer (number of minutes) |
string |
noReload |
Use it to forbid/allow reloads Default : false. |
boolean |
reloadDuration |
Default reload duration Type : Time ("hh:mm" or "hh:mm:ss") or Integer (number of minutes) |
string |
routingMethod |
Routing method Specifies routing method used for travel time and distance matrix computation Possible values are : * TIME : routes minimizing travel time are used * DISTANCE : routes minimizing travel distance are used Default : TIME. |
|
sendResultToWebhook |
Enable result export to webhook If enabled, optimization result will be sent to the webook you defined in Toursolver Cloud configuration. Possible values are : * NONE : result will not be sent automatically when optimization finishes. You will have to call the result or toursResult service to retrieve it. * ORDERS : the "orders" result will be sent to the specified webhook. See OptimResultResult object for details. * TOURS : the "tours" result will be sent to the specified webhook. See OptimToursResult object for details. Default : NONE. |
|
speedPattern |
Speed pattern name Specifies the speed pattern to be used for this optimization. "default_profile" is the internal name for the default speed pattern (its actual name in UI depends on your locale). You can use your own speed pattern (defined in Toursolver UI) but you will have to use its internal name : if you created a pattern called "Paris august speed pattern", its internal name will be "paris_august_speed_pattern". If set to null (or not defined), no speed pattern will be used at all
(same speeds for whole day). |
string |
startFromEvaluationInfo |
Enable this if you want the optimization to start from a specified initial configuration. Therefore, you must fill the evaluationInfos Default : false. objects in orders (see TSEvaluationInfos). |
boolean |
teamId |
If you did not specify any resource in your request, all resources
defined in your tenant will be used for this optimization. If you specify
a team identifier, only the resources of this team will be used. |
string |
useForbiddenTransitAreas |
Whether to use forbidden transit areas Specifies true to use forbidden transit areas, and false to ignore forbidden transit areas If omitted, default to true, but has no effect if no forbidden transit areas are supplied |
boolean |
useOTSolver |
Whether to use OTSolver instead of TSDK OTSolver is the new optimization engine behind Toursolver. It behaves better with big problems (more than 1000 visits). This is still a beta version and all the constraints supported by TSDK are not supported yet but they will be implemented as soon as possible. OTSolver must be enabled for your account before you can use it. |
boolean |
vehicleCode |
Vehicles regulations. Possible values are : * bicycle * bus * car * deliveryIntermediateVehicle * deliveryLightCommercialVehicle * emergencyTruck * emergencyVehicle * intermediateVehicle * lightCommercialVehicle * pedestrian * taxi * truck If not specified, vehicle type defined in UI will be used |
string |
The Order object stores order data.
Order is composed of X,Y coordinates, identity tags, a set of constraints and status reports.
Use the Orders object to specify your orders data. These elements can be considered as deliveries, pick-ups or commercial visits occuring at a specific locations.
The optimization process consists in assigning Orders elements to Resources elements in a way that respects the constraints of every element and minimizes the total cost of the planning.
Polymorphism : Composition
Name | Description | Schema |
---|---|---|
active |
Indicates whether the order should scheduled or not Default : True. |
boolean |
allSkillsRequired |
Indicates whether a resource must provide all required skills or one at least. * Set it to True to indicate that a resource must provide all the customer required skills. * Set it to False to indicate that a resource must provide at least one of the customer required skills. Default : True. |
boolean |
assignResources |
The identities of the resources that can deliver a customer. Use this constraint when you want some customers to be delivered by specific resources. Type : string array containing resources tag ID Default : not used. |
< string > array |
courierPenalty |
The cost of the order delivered by an independant transport device. Use this constraint when an order can be delivered independantly to specify the cost of the device. The solver engine will assign it to a courier device or integrate it in a tour according to the least cost. Type : float. Default : not used. |
number |
customDataMap |
Private feature data. Use this feature when you need to keep accessible private data about customers. For instance if you need to export the address of an element in a planning report, store it there. These informations can also be exported to the mobile app. max 50 fields Default : empty. |
< string, string > map |
customerId |
Example : |
string |
delayPenaltyPerHour |
The penalty per hour for being late at a customer. Use this constraint to allow a smarter control, with respect to time windows, than with the use of the tsOrderPunctuality constraint. Type : float. Default : not used. |
number |
email |
Example : |
string |
evaluationInfos |
first order assignment (specifying resource, day and position in route). Use it to compare optimization result with a previous optimization Warning : used only if startFromEvaluationInfo is set to true in options. |
|
excludeResources |
The identities of the resources which must not deliver a customer. Use this constraint when you want to prevent some customers from being delivered by specific resources. |
< string > array |
fixedVisitDuration |
The fixed part of the total time spent visiting a customer. Use this constraint to specify the minimum time spent at a customer’s. Use it to store the time needed by a vehicle to park, for instance, or the time planned for a commercial meeting. Type : Time ("hh:mm" or "hh:mm:ss") or Integer (number of minutes). Default : not used. Example : * tsOrderFixedVisitDuration = "00:30:00" indicates that the visit will be 30 minutes long. * tsOrderUnloadingDurationPerUnit = 120 indicates that 120 seconds are necessary to unload one unit. With a tsOrderQuantity equal to 8, for instance, the variable part is 120*8 (960 seconds or 16 minutes) to unload the customer ordered quantity. * Total delivery time = 30 minutes + 16 minutes = 46 minutes accounted
for the customer delivery. |
string |
frequency |
The visit occurrence within a defined period. Use this constraint to plan multiple visits at a customer during a period. Type: string value describing the number of visits over a period. Default: not used. Example : Frequency = "3/5" means a customer must be visited 3 times within a
5-days long period. The solver engine will create and optimize routes
respecting an optimal duration between consecutive visits. Thus, back to
the example, the computed period is 5/3 rounded = 2. The best solution
will respect, as far as possible, a 2-days long period between each visit
(ex: day1, day3, day5 is a good solution). |
string |
getNotifications |
boolean |
|
id |
The unique identifier of the order |
string |
label |
Example : |
string |
minDuration |
The min duration of the visit that enables partition. When the total duration of an order is very long, you may want to part it into multiple consecutive visits. First use this constraint to specify a duration threshold from which visit can be cut into multiple parts. Then use the tsOrderMinPartDuration to specify the min duration of one part. Type : Time ("hh:mm" or "hh:mm:ss") or Integer (number of minutes). Default : not used. |
string |
minPartDuration |
The min duration of a part of a split visit. When the total duration of an order is very long, you may want to part it into multiple consecutive visits. First use the tsOrderMinDuration to specify a duration threshold from which the visit can be cut into multiple parts. Then use this constraint to specify the min duration of one part. The visit is split into parts of the set duration, and eventually a bigger one. Type : Time ("hh:mm" or "hh:mm:ss") or Integer (number of minutes). Default : not used. |
string |
phone |
Example : |
string |
possibleVisitDaysList |
The possible visit days related to each visit time window. Use this constraint to specify the possible visit days of a customer referring to a visit time window. It must be related to the tsResourceWorkDays constraint of the resources, as resources work days define the planning period. You can plan visits on a 64-days-long period max. Type : array of string values containing visit days separated with commas (like "1, 2, 5" or "4, 20/05/2010") or intervals (like "1-10", "2=>5" or "22/05/2010=>03/06/2010"). For day intervals, prefer the "=>" separator. Be carrefull, if the separator of date is - then "1-5" corresponds to May the 1st of the current year. 1 is the first day of the planning period, the corresponding date, if any, is defined by the oldest date, for all resources, in the tsResourceWorkDays constraint. No date in the possible visit days description can precede the first day of the planning period defined by the resources (which is day 1). Default: 1=>64. You can set up to 4 sets of visit days in this array. If you define several time windows, each time window will apply to corresponding set of possible days : first time window applies to first possible days set, second time window applies to second possible days set, etc. Example : * Set it to "1" (or "14/05/2010) when a customer must be visited on the first day of the planning period. * Set it to "1, 2, 4, 5" (or "14/05/2010,15/05/2010,17/05/2010,18/05/2010") if the customer cannot be visited on the third day of a five days planning period. * Set it to "1=>5" (or "14/05/2010=>18/05/2010") to define a 5-days long period during which the customer can be visited. |
< string > array |
punctuality |
The priority for a customer to be delivered on time. Use this constraint to introduce different priority levels for the respect of visit time windows (when defined). Specify a value from 1 to 5 to set the priority: customers with a punctuality set to 5 will have less risk of delayed deliveries than a customer with a punctuality set to 1. You can specify more precisely punctuality requirements to enforce delay control by using the tsOrderDelayPenaltyPerHour constraint instead of the tsOrderPunctuality constraint. Type : integer value from 1 to 5. Default : 1. |
number |
quantities |
The requested product quantities for an order. Use this constraint to specify the product quantities ordered by a customer, for instance. Up to 24 quantities can be used to order different products. Useless when planning commercial tours. Type : float array (maximum of 3 significant digits after decimal separator). Default : 0 Max : 2,147,483. Example : * Use this constraint to store the number of ordered packages, when working with packages. * Use this constraint to store the number of ordered liters, when working with liquids. * Use multiple dimensions when working with multiple products: when delivering fuels for instance, you will use as many dimensions as types of fuels Warning : The quantity constraint of the Orders elements must be related to the corresponding capacity constraint of the Resources elements: thus, an order will not be planned whenever no resource with the related capacity has been defined. |
< number > array |
requiredSkills |
The list of the skills a customer requires to be visited. Use this constraint when an order must be affected to a specific kind of resource: these resources will have to provide the required skills to be able to visit the customer. Type : string array. Default : none. Example : * Specify the word "Maintenance" as a required skill for a maintenance visit. Only the resources providing the "Maintenance" skill can perform the visit. * Specify "Small vehicle" as a required skill for a customer living down town. |
< string > array |
resourceCompatibility |
Value for compatibility with resources. If the order has a compatibility constraint value, a resource is compatible with the order if its compatibility value is either non-existent either larger or equal to the order’s one. See tsResourceOrderCompatibility. Example : * Set tsOrderResourceCompatibility to 254.18 and tsResourceOrderCompatibility to 260.12: order and resource are compatible * Set tsOrderResourceCompatibility to 254.18 and tsResourceOrderCompatibility to 200: the order can not be affected to the resource * Set tsOrderResourceCompatibility to 254.18 and tsResourceOrderCompatibility empty: order and resource are compatible * Set tsOrderResourceCompatibility empty and tsResourceOrderCompatibility to 260.12: order and resource are compatible Type : double Default : -1 |
number |
sequenceNumber |
number |
|
timeWindows |
The visit time windows. Use this constraint to specify a visit time window during which the order can be delivered. A visit time window is defined by its start time, its end time and possible visit days (see tsOrderTimeWindow1_EndTime, tsOrderPossibleVisitDays1). You can specify up to 4 visit time windows for a customer. Type : array of time windows Default : "00:00:00". Example : A customer can only be delivered: * * on Monday from 11:00:00 to 12:00:00 AM and from 04:00:00 to 05:00:00 PM, * on Tuesday, Wednesday, Thursday from 08:00:00 to 09:00:00 AM and from 04:00:00 to 05:00:00 PM, * on Friday from 08:00:00 to 09:00:00 AM. Its visit time windows will be specified as follows: * first time window StartTime = "08:00:00", EndTime = "09:00:00", first set of possible days = "2=>5", * second time window StartTime = "11:00:00", EndTime = "12:00:00", second set of possible days = 1, * third time window StartTime = "16:00:00", EndTime = "17:00:00", third set of possible days = "1=>4". |
< json_TSTimeWindow > array |
travelTimeModifier |
Indicates the value of the travel time modifier. When reaching a location situated in a large city, one may want to take into account driving difficulties, such as narrow streets and congestion. The travel time modifier enables to increase the travel times around a location. It is describes by three values. The value by which multiply the travel times around the location (tsOrderTravelTimeModifierValue), the portion of the travel time on which the modifier applies (tsOrderTravelTimeModifierLength) an offset to add to any travel duration leaving or reaching the location (tsOrderTravelTimeModifierOffSet). Example : * Set tsOrderTravelTimeModifierValue to 1.5, tsOrderTravelTimeModifierLength to 300 and tsOrderTravelTimeModifierOffSet to 60 for Order 1 * Set tsOrderTravelTimeModifierValue to 2, tsOrderTravelTimeModifierLength to 420 and tsOrderTravelTimeModifierOffSet to 0 for Order 2 If the initial travel duration between Order 1 and Order 2 was 1000, one obtains a travel time 360 * 1.5 + 60 + 280 + 420 * 2 + 0 = 1660 Type : float Default : 1 |
|
tsOrderBefore |
Example : |
string |
tsOrderBeforeMaxTimeSpacing |
Example : |
string |
tsOrderBeforeMinTimeSpacing |
Example : |
string |
tsOrderFixed |
If true force the use of the specified day, resource and start time |
boolean |
tsOrderLastVisit |
The number of days before the beginning of the planning the last visit belonging to the order has been performed Use this constraint in case of a frequency order to specify from how many days the last visit was performed before starting the current planning. The default value indicates this constraint is to be unused in the planning. Type : negative integer Default : 0 Max : -2,147,483. Example : If tsOrderLastVisit = -2, the last visit of the same order has been performed two days ago. Warning : if the number of occurences of the frequency is more than one, the constraints tsOrderLastVisit and tsOrderMinimumSpacing are not considered. |
number |
tsOrderMaximumSpacing |
The maximum number of days required between two visits of a same order. Use this constraint in case of frequency order to specify how many days at most should be left between two visits of the order. Type : integer Max : 2,147,483. |
number |
tsOrderMinimumSpacing |
The minimum number of days required between two visits of a same order. Use this constraint in case of frequency order to specify how many days at least should be left between two visits of the order. Type : integer Default : 0 Max : 2,147,483. Warning : if the number of occurences of the frequency is more than one, the constraints tsOrderLastVisit and tsOrderMinimumSpacing are not considered. |
number |
type |
The type of visit at a customer. * 0 (Delivery): the resource will delivere related quantities. * 1 (PickUp): the resource will pick-up related quantities. * 2 (DeliveryFirst): the resource will not mix deliveries and pick-ups in a same rotation. It is possible to mix pickups and 0 type deliveries in the same rotation. However, the delivered products will come from the depot and the pickup products will be unloaded at the depot. No product delivered to a customer can come from a pickup at another customer’s. Type : Integer. Default : 0 (Delivery). |
number |
unloadingDurationPerUnit |
The time needed to deliver one unit of product. Use this constraint when the time spent at a customer depends on the quantity to deliver. It is the time needed to unload one unit of the quantity stored in the customer tsOrderQuantity constraint. Type : Time ("hh:mm" or "hh:mm:ss") or Integer (number of minutes). Default : not used. |
string |
wholeVisitInTimeWindow |
Whole visit ends before time window end. Use this constraint if you want that a visit ends before the end of the time window. Default : false. |
boolean |
x |
longitude of order location |
number |
y |
latitude of order location |
number |
Name | Description | Schema |
---|---|---|
duration |
Duration Type : Time ("hh:mm" or "hh:mm:ss") or Integer (number of minutes). |
string |
end |
maximum end time Type : Time ("hh:mm" or "hh:mm:ss") |
string |
start |
minimum start time Type : Time ("hh:mm" or "hh:mm:ss") |
string |
Details of a stop within a resource tour.
Name | Description | Schema |
---|---|---|
dayId |
day of the stop |
string |
resourceId |
Assigned resource identifier |
string |
stopDriveDistance |
The drive distance from the previous to the current stop. |
number |
stopDriveTime |
The drive time from the previous to the current stop. Type : Time ("hh:mm" or "hh:mm:ss") |
string |
stopDuration |
The duration of the stop. Type : Time ("hh:mm" or "hh:mm:ss") |
string |
stopElapsedDistance |
The tour cumulated driven distance at the stop. |
number |
stopId |
the ID of the stop or order |
string |
stopPosition |
The position of the stop in the resource tour. |
number |
stopStartTime |
The time the stop starts at. Type : Time ("hh:mm" or "hh:mm:ss") |
string |
stopStatus |
The status of the stop. An order can be on time, late, waited, impossible (non compliant). It can also be a courier service delivery and not planned. See StopStatusConstants for more information about stop status. Type : integer. * 0 = OnTime: The stop begins into the specified visit time window. * 1 = Late: The stop begins after the specified visit time window. * 2 = Waited: The resource waits at the stop for the specified stop start time. * 3 = Impossible: The stop cannot be planned. * 4 = BadDay: The stop is planned without respect of frequency. * NotPlanned: The courier service is in charge of a stop or the stop is not included in the planning process. * BadPrevious : When the visits are split, the parts should follow one another. This status is that of a part following another visit instead of the previous part of the split visit. |
number |
stopType |
The stop type A tour is composed of stops, which can be either customers visits or breaks, like reload breaks, lunch breaks, or even night breaks. StopTypeConstants are * 0 = Visit: The stop is an element of the Orders object. * 1 = Start: The stop is the initial stage (departure) of the tour, occurring at the resource’s start location. * 2 = End: The stop is the the last stage (arrival) of the tour, occurring at the resource’s stop location. * 3 = EndBeforeOvernight: The stop is the the last stage (arrival) of the tour, occurring where the resource stopped for the night. * 4 = ReloadBreak: The stop is a reload break within the tour, occurring at a depot location. * 5 = LunchBreak: The stop is the lunch break within the tour, occurring anywhere between two other located stops. * 6 = RestBreak: The stop is a rest break within the tour, occurring anywhere between two located stops. * 7 = WaitBreak: The stop is a wait break within the tour, occurring before a visit. * 8 = StartAfterOvernight: The stop is the last stage (arrival) of the tour, it occurs where the resource stopped for the night. tsStopDriveDistance * 9 = Briefing: The stop is a briefing break within the tour, occurring right after the departure of the tour. * 10 = DeBriefing: The stop is a wait break within the tour, occurring right before the arrival of the tour. |
number |
stopX |
The X coordinate of the stop. |
number |
stopY |
The Y coordinate of the stop. |
number |
The Resources object stores the collection of the elements which will perform deliveries, pick-ups, commercial visit, etc.
Each element can be seen as a driver/vehicle pair and their related driving and working constraints.
It is composed of an identity tag, and location coordinates (base or depot, departure, arrival location). Eventually, each element can be configured through a set of constraints which stores information like capacity, driver work time, penalties and so on.
Polymorphism : Composition
Name | Description | Schema |
---|---|---|
additionalCostOperator |
Operator used to compute additional cost (see toursResult object) Possible values are : * SUM : tour additional cost will be the sum of additional costs of planned orders * MAX : tour additional cost will be the maximum value of additional costs of planned orders * MIN : tour additional cost will be the minimum value of additional costs of planned orders * AVERAGE : tour additional cost will be the average of additional costs of planned orders |
|
additionalCostOrderCustomDataName |
Name of TSOrder customData that will contain the TSOrder type used for
additional cost computation (see toursResult object) |
string |
additionalCosts |
List of additional cost (cost per order type) |
< json_TSAdditionalCost > array |
available |
Indicates whether a resource is included in the planning process or not. This constraint enables you to easily modify your optimization problem configuration without having to add nor delete original data. * Set it to True to include a resource element in the planning process. * Set it to False to ignore it: it will not be used in the planning. Type : Boolean. Default : not used. |
boolean |
avgConsumption |
Average consumption of the resource. Use this constraint to specify the average consumption of the resource. This consumption must be defined in liters per 100 distance unit (km or miles) Default : The consumption indicated in the
VehicleProfile.Consumption property. |
number |
briefingDuration |
An additional duration applied before the tour starts. Use this constraint to specify an additional duration before the resource begins the tour. For instance, to brief drivers before they leave or to simulate an initial vehicle loading time (no depot). Type : "hh:mm:ss", DateTime. Default : "00:00:00". |
string |
capacities |
The total product capacity a resource can carry. Use this constraint to specify the amount of product a resource can deliver or pick-up. It must be linked with the customers related quantity constraint. 23 more dimensions can be used in order to specify various products. They must be linked with the customers related dimensions. Type : float (maximum of 3 significant digits after decimal separator). Default: None. Max : 2,147,483. Example : * Use it to store the total number of packages a resource can deliver before reloading, when working with packages. * Use it to store the total number of litres a resource can deliver before reloading, when working with liquids. * Use multiple capacity dimensions when working with multiple products: when delivering fuels, you will use as many capacities as types of fuels. |
< number > array |
customDataMap |
Private custom data. Use this feature when you need to keep attributes values of your own into the optimization context. For instance if you need the address of an element, store it there. |
< string, string > map |
dailyWorkTime |
The maximum resource work duration over a day. Use this constraint to specify the maximum daily work duration (unless overtime periods have been defined). If the dailyWorkTime constraint is not set to a value, default daily work time is computed from resource time window and lunch duration (workStartTime, workEndTime and lunchDuration). Type : "hh:mm:ss", DateTime. Default : not used. |
string |
debriefingDuration |
An additional duration applied at the end of the tour. Use this constraint to specify an additional duration after the resources stops at the end location. For instance, to debrief drivers after their tour or to account an ultimate vehicle unloading time, or a parking time. Type : "hh:mm:ss", DateTime. Default : "00:00:00". |
string |
driveRestAtCustomer |
Indicates whether or not time spent at customer during deliveries can be considered as rest break. * Set it to True if a visit can be considered as a rest break, as soon as its duration is equal or higher than the legalMinRestDuration constraint. * Set it to False if not. Type : Boolean. Default : False. |
boolean |
driveRestAtDepot |
Indicates whether time spent at depot during a reload break can be considered as drive break or not. Use this constraint to take into account drive time legislation in your planning results. * Set it to True if load breaks can be considered as drive breaks, as soon as their duration is equal or higher than the legalMinRestDuration constraint. * Set it to False if not. Type : Boolean. Default : False. |
boolean |
endX |
longitude of resource arrival Specify it only if arrival and start are not the same. |
number |
endY |
latitude of resource arrival Specify it only if arrival and start are not the same. |
number |
extraTravelPenalties |
The costs for a resource of driving for one distance unit. |
< json_TSTravelPenalty > array |
fixedLoadingDuration |
The fixed duration of the resource load break. Use this constraint to specify how long takes a resource reload at depot. You can specify an additional duration according to the quantity to reload, using loadingDurationPerUnit. Type : "hh:mm:ss", DateTime. Default : "00:00:00". Example : * fixedVisitDuration = "00:30:00" indicates that 30 minutes are needed to load the resource. * loadingDurationPerUnit = 120 indicates that 120 sec are needed to load one unit. If the quantity to reload is 8, for instance, the variable part is 120*8. 16 minutes are required to load the resource. * Total load time = 30 minutes + 16 minutes = 46 minutes accounted for
this reload break. |
string |
fixedUnloadingDuration |
The fixed time needed for the resource to deliver/pick-up at the customer’s place. This fixed resource’s unloading duration is added to the resource’s unloading duration depending on the quantity to deliver/pick-up and to the order’s unloading duration depending on the quantity to deliver/pick-up. See also tsResource unloadingDurationPerUnit and tsOrder unloadingDurationPerUnit. Example : * Set tsOrderQuantity to 3. * Set tsOrder unloadingDurationPerUnit to 2 mn and tsResource fixedUnloadingDuration and tsResource unloadingPerUnit to 0 or empty: the variable part of the order is 6 mn * Set tsOrder unloadingDurationPerUnit to 2 mn and tsResource fixedUnloadingDuration to 10 mn and tsResource unloadingPerUnit to 0 or empty: the variable part of the order is 10 mn * Set tsOrder unloadingDurationPerUnit to 2 mn and tsResource fixedUnloadingDuration empty and tsResource unloadingPerUnit to 1 mn: the variable part of the order is 3 mn Type : "hh:mm:ss", DateTime. Default : "" Warning : the fixed/per unit unloading duration for resource is not
compatible with the orders constraints: partition and whole visit in time
window. Hence if one of the constraint at least tsResource
fixedUnloadingDuration and tsResource unloadingDurationPerUnit is non
null, partition and whole visit in time window are disabled. |
string |
fuelCode |
Vehicles fuel type. Possible values are : * diesel * undefined * unleaded |
string |
fuelType |
The fuel type of the resource. Use this constraint to specify the fuel type of the resource. Available fuel types are : * 0: Unknown fuel type * 1: No fuel type (pedestrian) * 2: Diesel * 3: Unleaded fuel * 4: LPG Type : Integer. Default : The fuel type indicated in the VehicleProfile.FuelType property. |
number |
globalCapacity |
Global capacity for a resource. This constraint unables to set a maximum capacity on a resource, whatever product is carried. If both global capacity and capacity per product are to be used, set True for the value of useAllCapacities. Type : Float Default : None Max : 2,147,483. Example : Set globalCapacity = 15 and useAllCapacities = False. The global capacity only is considered: the vehicle can carry 15 quantities of products, whatever product is to be carried. |
number |
id |
The unique identifier of the resource. This id can not contain special characters like = or : |
string |
legalDailyDriveDuration |
The legal daily duration a resource can drive before having a rest break. Use this constraint to take into account drive time legislation in your planning results. Specify the rest duration in the legalDailyRestDuration: rest breaks occur as soon as the resource has driven the legal daily driving duration or has completed its daily work time. Type : "hh:mm:ss", DateTime. Default : not used. Example : legalDailyDriveDuration = "09:00:00",
legalDailyRestDuration = "11:00:00". The resource can cumulate a 9-hours
daily drive time before having to rest during 11 hours. |
string |
legalDailyRestDuration |
The legal rest duration a resource must have after the daily max drive duration. Use this constraint to take into account drive time legislation in your planning results. Rest breaks occur as soon as the resource has driven the legal max daily duration or has complete its daily work time. The use of both legalDailyDriveDuration and legalDailyRestDuration implies that the start and end time of tours are no longer defined by the workStartTime and workEndTime constraints, but may vary as long as the legalDailyRestDuration constraint is respected. Type : "hh:mm:ss", DateTime. Default : not used. |
string |
legalDriveRestDuration |
The resource break duration after max drive duration. Use this constraint to take into account drive time legislation in your planning results. Type : "hh:mm:ss", DateTime. Default : not used. |
string |
legalMaxDriveDuration |
The legal max duration a resource can drive without a break. Use this constraint to take into account drive time legislation in your planning results. Type : "hh:mm:ss", DateTime. Default: : not used. Example : * legalMaxDriveDuration = "04:30:00", legalDriveRestDuration = "00:45:00". The resource can drive for 4 hours and 30 minutes before having a 45 minutes break. Then it can start driving again for 4 hours and 30 minutes???etc. * If added driveRestAtCustomer = True and legalMinRestDuration =
"00:15:00", rest time is cumulated as soon as customer visit duration is
equal or higher than the specified min rest duration. If the 45 minutes
rest break has not occured when the resource has driven for 4 hours and
30 minutes, it must stop to complete the break. Otherwise, it can drive
again for 4 hours and 30 minutes. |
string |
legalMinRestDuration |
The minimum duration a resource breaks for it to be considered as a drive break. Use this constraint to take into account drive time legislation in your planning results. When breaks occur at customer or at depot, they are considered as drive breaks if their duration is equal or higher than the specified min rest duration. Type : "hh:mm:ss", DateTime. Default: : not used. |
string |
loadBeforeDeparture |
Indicates whether a resource must load before starting a tour or not. * Set this constraint to True to insert a load break at depot before the tour starts. * Set it to False to consider the vehicle loaded. Type : Boolean. Default: : False. |
boolean |
loadOnReturn |
Indicates whether a resource must reload after a tour or not. * Set this constraint to True to insert a load break at depot after the tour ends. * Set it to False to not reload the vehicle. Type : Boolean. Default: : False. |
boolean |
loadingDurationPerUnit |
The time needed to load a unit of product. This constraint is added to the fixed part of the loading duration: it depends on the total quantity to load. Type : "hh:mm:ss", DateTime, Integer (number of seconds). Default:
: 0. |
string |
lunch |
The lunch break Default: : no lunch break |
|
maxNightsOutPerJourney |
The number of nights a resource can spend out to perform deliveries before coming back to base. Use this constraint to enable night breaks trip: it will store how many days a resource can drive away from depot. Unless the vehicle needs to reload, it will not come back before. Type : integer. Default: : not used. Example: maxNightsOutPerJourney = 4, workDays = 1=>5. The resource can perform deliveries during 5 days (and 4 nights) without coming back to depot. Starting on day 1, it must come back to depot on day 5. |
number |
maximumDistance |
The maximum distance the resource should travel per day. Use this constraint to specify the distance the resource should not exceed in one day Type : integer Default : -1 (no limit) |
number |
maximumReloads |
Value for maximum number of reloads per day. |
number |
maximumReloadsPenalty |
Value of the penalty if the resource exceeds the maximum number of reloads per day. If the resource exceeds the maximum number of reloads per day, it will be penalized by the maximum reloads penalty multiplied by the number of reloads' overtaking. The default value is 1024 if the constraint maximumReloads is set. See also maximumReloads. |
number |
maximumVisits |
The maximum number of visits the resource can perform in one day. Type : integer Default : -1 (no limit) Max : 2,147,483. |
number |
minDriveDuration |
The minimum laps of time between 2 consecutive visits. Use this constraint to specify a minimum drive time accounted when consecutive visits are very close, in order to compute a realistic timing. Type : "hh:mm:ss", DateTime. Default: : not used. |
string |
minimumQuantity |
Value for minimum quantity to deliver. If the resource has a non null minimum quantity to deliver constraint value, the resource can visit on order only if the quantity to be picked-up or delivered at this order is higher than the constraint value. *Example : * * set order quantity to 3 and resource minimumQuantity to 2 : resource might visit the order * set order quantity to 3 and resource minimumQuantity to 5 : resource can not visit the order Type : float |
number |
mobileLogin |
Mobile login to be specified only if you need to be able to export the
optimization result to operation planning from TsCloud GUI. If you
trigger operational planning export from the API, you will still need to
specify the mapping between resource name and login. |
string |
nightPenalty |
The night cost of a resource when planning night breaks. Use this constrainte to specify how much a night out costs (lunch, bed, breakfeast???) for a resource when night breaks are allowed. Type : float. Default: : 0 |
number |
noReload |
Constraint providing resource to reload at depot during a tour. If none of the constraints loadBeforeDeparture and loadOnReturn is activated, the resource is never loading at depot. If one of these constraint is activated the resource is loading once per tour, either at the beginning of the tour or at the end of it. If both constraints are activated then the resource is loading twice a tour, at the beginning and at the end. With standard solver only : solver always works with solution cost comparison, so it may allow reloads even if you set noReload to true if the solution cost is really lower. The only way to totally prevent reloads is to set fixedLoadingDuration to a very long duration (20:00:00 for instance). The solver will warn you about this long duration but will not add reloads to the tours. Caution : Don’t do this if you are using loadOnReturn or loadBeforeDeparture Default : False |
boolean |
nonUsePenalty |
A cost paid for NOT using a resource in the computed planning. Use this constraint to penalize the fact that an available resource is not used in the planning. It proves usefull when you must use all the resources in the Resources collection: you will prevent the solver from optimizing the number of resources, as using them would be too expensive a solution. Type : float. Default: : not used. Example : Use it to specify parking taxes when a vehicle performs no tour. |
number |
openDistanceStart |
boolean |
|
openDistanceStop |
boolean |
|
openStart |
Indicates whether or not a tour evaluation starts from the resource start location or from the first customer’s place. * Set it to True to begin the tour at the first customer (no cost will be computed between the resource start location and the first customer). * Set it to False to begin the tour at the resource start location. Type : Boolean. Default: : False. |
boolean |
openStop |
Indicates whether or not a tour evaluation ends at the last customer’s place or at the resource end location. * Set it to True to finish the tour at the last customer location (no cost will be computed between the last customer and the resource end location). * Set it to False to finish the tour at the resource end location. Type : Boolean. Default: : False. |
boolean |
openTimeStart |
boolean |
|
openTimeStop |
boolean |
|
optimumStartTime |
Adapts the resource start time to the best solution. * Set this constraint to False to start the tour at the time indicated by the workStartTime constraint. * Set this constraint to True to optimize the resource start time and enable the use of the dailyWorkTime constraint. Notice that, in both cases, the tour will not start before the time stored in the workStartTime constraint and that the use of the weeklyWorkTime constraint is enabled. Type : Boolean. Default: : False. |
boolean |
otherWorkEndTimes |
The end time of the resource work time window for the "other working days" (see otherWorkDaysList). If you defined other working days, use this constraint to specify the time at which the tour must end. These times can be adjusted using the optimumStartTime parameter. You can define up to 3 different end times here, corresponding to the different "other working days" slots. Type : List of "hh:mm:ss", DateTime. Example :
["18:00:00","19:00:00] |
string |
otherWorkStartTimes |
The start time of the resource work time window for the "other working days" (see otherWorkDaysList). If you defined other working days, use this constraint to specify the time at which the tour must start. These times can be adjusted using the optimumStartTime parameter. You can define up to 3 different start times here, corresponding to the different "other working days" slots. Type : List of "hh:mm:ss", DateTime. Example :
["08:00:00","09:00:00] |
string |
otherWorkingDays |
Other working days (see workingDays) You can define up to 3 different working days slots. If you do so, you can then specify distinct work start and end times with otherWorkStartTimes and otherWorkEndTimes. Type : List of string (see workingDays format) Example : ["2","3=>5"] |
< string > array |
overnightMinDriving |
The max duration a resource can drive to go back to base at the end of a tour when working with night breaks. Use this constraint when a resource can end a tour at base instead of having a night break on the road. Type : "hh:mm:ss". Default: : not used. |
string |
overtimeDurations |
The duration of the resource overwork periods. (max 2 periods) Use this constraint when you need to define 2 different overwork periods with regard to daily work time and their related surcharge. No overwork period can be defined with regard to weekly work time. Type : "hh:mm:ss", DateTime. Default: : not used (no second overtime period). Example : workPenalty = 10, first overtime duration = "02:00:00", first overtime penalty = 5,second overtime duration = "01:00:00", second overtime penalty = 10. The cost of the resource during the daily working time is 10 euros per hour. The resource can work during 3 more hours and each overworked hour will cost 10 + 5 euros for 2 hours and 10 + 10 euros for the last hour. |
< object > array |
overtimePenalties |
A surcharge for a resource’s overwork period (max 2 periods). Use this constraint to specify additional cost to workPenalty as overwork time. You can define up to 2 overwork periods with regard to daily work time and their related surcharge. No overwork period can be defined with regard to weekly work time. Type : float. Default: : not used. Example : workPenalty = 10, first overtime duration = "02:00:00", first overtime penalty = 5. The cost of the resource during the daily working time is 10 euros per hour. The resource can work during 2 hours after the daily working time and each overworked hour will cost 15 (10 + 5) euros. |
< number > array |
payWholeDay |
Indicates whether or not a whole work day cost is computed as soon as a resource works even a few hours. * Set this constraint to True to account a whole day cost. * Set it to False to account only effective worked hours. Type : Boolean. Default: : False. |
boolean |
penaltyPerVisit |
An additional fixed cost applied each time the resource performs a visit. Use this constraint when the cost of a resource may vary according to the number of visits it performs. Type : float. Default: : 0. |
number |
providedProducts |
The list of products provided by a resource. This constraint is linked with tsDepot requiredProducts constraint: a depot with a required product can only be visited by a resource providing it. Type : string as a list of products separated with commas. Default : not used. Example : Specify "Oxygen" in the resource can provide oxygen. |
string |
providedSkills |
The list of characteristics provided by a resource. This constraint is linked with the same order constraint: a customer with a required skill can only be delivered by a resource providing it. Type : string as a list of characteristics separated with commas. Default: : not used. Example : * Specify "Maintenance" in the provided skills of a resource designed to perform maintenance visits type. * Specify "Small vehicle" to the provided skills of a resource able to
perform downtown visits. |
string |
speedAdjustment |
A factor to increase or decrease the vehicle speed. Whenever users observe a significant gap between estimated speeds and the real ones, they can adjust them by using this factor. It is expressed as a percentage of the used speed. Type : float. Default: : not used. Example : * speedAdjustment = 110: resource speeds will be 10% higher than the used speeds. * speedAdjustment = 80: resource speeds will be 20% lower than the used speeds. |
number |
startTravelTimeModifier |
travel time modifier associated with the start location of the resource |
|
startX |
longitude of resource start (and arrival if no endX provided) |
number |
startY |
latitude of resource start (and arrival if no endY provided) |
number |
stopTravelTimeModifier |
travel time modifier associated with the stop location of the resource |
|
tomTomWebFleetEnabled |
boolean |
|
tomTomWebFleetIdentifier |
Example : |
string |
travelPenalty |
The cost for a resource of driving for one distance unit. Use this constraint to specify the average resource taxes (gazoline, wear,???) when driving one distance unit. Type : float Default : 1.5 Example : if travelPenalty = 0.5 (euro per distance unit) and the driven distance is about 100 unit (km or miles), the total distance cost is 0,5 * 100 = 50 euros. |
number |
travelTimeModifier |
travel time modifiers When reaching a location situated in a large city, one may want to take into account driving difficulties, such as narrow streets and congestion. The travel time modifier enables to increase the travel times around a location. It is describes by three values. The value by which multiply the travel times around the location travelTimeModifierValue), the portion of the travel time on which the modifier applies (travelTimeModifierLength) an offset to add to any travel duration leaving or reaching the location (travelTimeModifierOffSet). Example : * Set travelTimeModifierValue to 1.5, travelTimeModifierLength to 300 and travelTimeModifierOffSet to 60 for Resource 1 * Set travelTimeModifierValue to 2, travelTimeModifierLength to 420 and travelTimeModifierOffSet to 0 for Order 1 If the initial travel duration between Resource 1 and Order 1 was 1000, one obtains a travel time 360 * 1.5 + 60 + 280 + 420 * 2 + 0 = 1660 |
|
unloadingDurationPerUnit |
the time needed to the resource to deliver/pick-up one unit of product at the customer’s place. This resource’s duration is added to the fixed resource’s unloading duration and to the order’s unloading duration depending on quantity to deliver/pick-up. See also tsResource fixedUnloadingDuration and tsOrder unloadingDurationPerUnit. Example : * Set tsOrderQuantity to 3. * Set tsOrder unloadingDurationPerUnit to 2 mn and tsResource fixedUnloadingDuration and tsResource unloadingPerUnit to 0 or empty: the variable part of the order is 6 mn * Set tsOrder unloadingDurationPerUnit to 2 mn and tsResource fixedUnloadingDuration to 10 mn and tsResource unloadingPerUnit to 0 or empty: the variable part of the order is 10 mn * Set tsOrder unloadingDurationPerUnit to 2 mn and tsResource fixedUnloadingDuration empty and tsResource unloadingPerUnit to 1 mn: the variable part of the order is 3 mn Type : "hh:mm:ss", DateTime. |
string |
useAllCapacities |
Determines if both global capacity and capacities per product should be considered in the optimization or only global capacity. Type : Boolean Default : False Example : Set globalCapacity = 15 and useAllCapacities = False. The global capacity only is considered: the vehicle can carry 15 quantities of products, whatever product is to be carried. |
boolean |
useInPlanningPenalty |
Penalty value if the resource is used in the planning. Use this constraint to specify the penalty if the resource is used at least one day in the planning Type : float Default : 0 |
number |
usePenalty |
A cost paid for using the resource in the computed planning. Use this constraint to ponderate the cost of using a resource element of the Resources collection, when working with rented vehicle for instance. You can use it as well to reduce the number of resources used to perform the deliveries. Type : float. Default: : not used. Example : Add the cost of use to the distance and hourly costs when working with a service provider. The solver, aiming at cost reduction, will try to eliminate this resource first, as it is the most expensive. |
number |
vehicleCode |
Vehicles regulations. Possible values are : * bicycle * bus * car * deliveryIntermediateVehicle * deliveryLightCommercialVehicle * emergencyTruck * emergencyVehicle * intermediateVehicle * lightCommercialVehicle * pedestrian * taxi * truck If not specified, vehicle type defined in UI will be used Only new solver can handle optimization with several types of vehicle. If
you use standard solver, you should specify the vehicle code only in the
options object. |
string |
weeklyWorkTime |
The maximum resource work duration over a week. Use this constraint to specify the maximum weekly work duration. Weeks are defined as follows: * year’s week, from monday to sunday, if a date has been specified in the workDays constraint * days 1 to 7 are the days of the first week and the second week start on day 8 if no date has been specified in the workDays constraint. No over work with regard to the weekly work duration is allowed. Type : "hh:mm:ss", DateTime. Default: : "168:00:00". |
string |
workEndTime |
The end time of a resource work time window. Use this constraint to specify the time at which the tour must be over or the daily work duration. * If the optimumStartTime parameter is set to True and the dailyWorkTime or weeklyWorkTime constraint value is set by user, the tour cannot finish later than the value of the workEndTime parameter, whatever overtime may be allowed by the overtime1_Duration and overtime2_Duration constraints. * If the optimumStartTime parameter is set to True and the dailyWorkTime constraint value is not set, the end time of the tour can be adjusted to match the begining of the work time window. In this case, this parameter is used only to compute the resource daily work time and the tour can finish at midnight. * If the optimumStartTime parameter is set to False, then this parameter is used to compute the resource daily work time and the tour can finish no later than the specified end time plus the values of the first overtime duration and the second overtime duration constraints. If the daily work duration is specified by the workEndTime constraint’s value, then it is equal to workEndTime minus workStartTime and lunchDuration. Example : For a vehicle to work for 6 hours between 7PM and 7AM, set * optimumStartTime=True * dailyWorkTime="06:00:00" * workStartTime="07:00:00" * workEndTime="19:00:00" For a vehicle to work for 8 hour between 8PM and 5AM with a one-hour break at 12:30, set * workStartTime="08:00:00" * workEndTime="17:00:00" * lunchDuration="01:00:00" * lunchTime="12:30:00" Type : "hh:mm:ss", DateTime. Default: : "24:00:00". |
string |
workPenalty |
The cost of a resource working for an hour. Use this constraint to specify the resource wages when working for an hour. Type : float. Default: : 9. Example : If workPenalty = 10 (euros per hour) and daily work time is about 8 hours, the total daily work cost is 10 * 8 = 80 euros. |
number |
workStartTime |
The start time of the resource work time window. Use this constraint to specify the time at which the tour must start. This time can be adjusted using the optimumStartTime parameter. Type : "hh:mm:ss", DateTime. Default: : "00:00:00". |
string |
workingDays |
The resource’s work days. Use this constraint to specify the days a resource works in the planning period. This constraint is linked with the orders possible visit days constraints of Orders object elements and with the depot days of opening constraints of Depots object elements. Thus, customers and resources must have matching days for deliveries to be possible, and depots must be opened on resources working days to be used. A maximum of 64 days can be defined as work days. Working days can be written as integers (1,2???) or dates (14/05/2010, 15/05/2010, ???). If you are using dates, the oldest date in the workDays constraint defines day 1. Type : string values containing days separated with commas (like "1, 2, 5" or "14/05/2010, 15/05/2010, 18/05/2010" to specify day 1, day 2 and day 5) or intervals (like "1-10", "2=>5" or "14/05/2010=>24/05/2010") where 1 (or 14/05/2010) is the first day of the planning period. For day intervals, prefer the "=>" separator. Be careful, if the separator of date is - then "1-5" corresponds to May 1st of the current year. If you mix integer and date formats, beware that day 1 will all the same be defined by the oldest available date. Default: : "1". Example : You can define a single working day: Specify "1", "3" or "10" for the resource to work on day 1, day 3 or day 10 of the planning period. You can also define working periods. Specify "1-5" or "1=>5" or "14/05/2010=>18/05/2010" for the resource to work on a 5-days period (from day 1 to day 5 included). You can also mix single day and periods. Specify "1, 3=>5" for the
resource to work on day 1 and from day 3 to 5 of the planning period. |
string |
Name | Description | Schema |
---|---|---|
depotProperties |
< string > array |
|
depots |
< json_TSDepot > array |
|
nbCapacities |
number |
|
nbExtraTravelPenalties |
number |
|
nbQuantities |
number |
|
nbTimeWindows |
number |
|
options |
||
orderProperties |
< string > array |
|
orders |
< json_TSOrder > array |
|
resourceProperties |
< string > array |
|
resources |
< json_TSResource > array |
Time window
Name | Description | Schema |
---|---|---|
beginTime |
the minimum begin time Type : Time ("hh:mm" or "hh:mm:ss") |
string |
endTime |
the maximum end time Type : Time ("hh:mm" or "hh:mm:ss") |
string |
Details of a stop within a resource tour.
Name | Description | Schema |
---|---|---|
additionalCost |
Additional cost Additional cost depends on additional cost configuration specified on resources and orders |
number |
dayId |
day of the tour |
string |
deliveryCost |
Total delivery cost of the tour Delivery cost depends on PenaltyPerVisit defined on resources and configuration specified in options (see countDepotsInDeliveryCost and countVisitCostOnceIfSameLocation) |
number |
plannedOrders |
Orders planned in this tour |
< json_TSPlanned > array |
reloadNb |
ReloadNb Number of reloads during this tour |
number |
resourceCapacities |
List of resource capacities |
< number > array |
resourceId |
Assigned resource identifier |
string |
totalCost |
Total cost Total cost = (delivery cost) + (additional cost) |
number |
travelDistance |
drive distance for this tour |
number |
travelDuration |
drive duration for this tour |
string |
usedCapacities |
List of used capacities Tour used capacities can exceed resource capacities if the tour contains one or several stops to a depot. |
< number > array |
Name | Description | Schema |
---|---|---|
distance |
The driven distance (in the solver’s measurement system unit) from which distance cost will be applied. Use this constraint when you need to specify a distance cost which can vary according to the covered distance. Up to 4 different distance costs can be specified. Each one must be related to the corresponding distance threshold, from which it will be applied |
number |
penalty |
The cost for a resource of driving for one distance unit. Use this constraint to specify the average resource taxes (gazoline, wear,???) when driving one distance unit. Type : float Default : 1.5 Example : if penalty = 0.5 (euro per distance unit) and the driven distance is about 100 unit (km or miles), the total distance cost is 0,5 * 100 = 50 euros. |
number |
Name | Description | Schema |
---|---|---|
length |
Indicates the duration on which to apply the travel time modifier. Type : Time ("hh:mm" or "hh:mm:ss") or Integer (number of minutes). Default : 0 |
string |
offset |
Indicates the offset of the travel time modifier. Type : Time ("hh:mm" or "hh:mm:ss") or Integer (number of minutes). Default : 0 |
string |
value |
Indicates the value of the travel time modifier. When reaching a location situated in a large city, one may want to take into account driving difficulties, such as narrow streets and congestion. The travel time modifier enables to increase the travel times around a location. It is describes by three values. The value by which multiply the travel times around the location (tsDepotTravelTimeModifierValue), the portion of the travel time on which the modifier applies (length) an offset to add to any travel duration leaving or reaching the location (offSet). Example : * Set tsResource TravelTimeModifier Value to 1.5, tsResource TravelTime Modifier Length to 300 and tsResource TravelTimeModifier OffSet to 60 for Resource 1 * Set tsDepot TravelTimeModifier Value to 2, tsDepot TravelTimeModifier Length to 420 and tsDepot TravelTimeModifier OffSet to 0 for Depot 1 If the initial travel duration between Resource 1 and Depot 1 was 1000, one obtains a travel time 360 * 1.5 + 60 + 280 + 420 * 2 + 0 = 1660 Type : float Default : 1 |
number |
Unplanned order
Name | Description | Schema |
---|---|---|
reason |
the reason why it what not planned |
string |
stopID |
The id of the stop. |
string |
Warning message (and associated error code) about possible Orders and Resources elements constraints misconfiguration.
The Solver object checks automatically data configuration (if not done yet) before the optimization begins. Whenever values are detected as incoherent or invalid, warnings are emitted in the Warnings property of the involved element. Depending the warning, constraints value can be replaced by their default value or not.
Name | Description | Schema |
---|---|---|
constraint |
id of constraint causing the warning |
number |
constraintName |
Example : |
string |
i18nMessageCode |
Example : |
string |
id |
if of object causing the warning |
string |
message |
warning message |
string |
messageId |
number |
|
objectType |
type of object causing the warning |
string |
value |
Example : |
string |
generic result of service
Name | Description | Schema |
---|---|---|
message |
error message |
string |
status |
response status, OK or ERROR |
Polymorphism : Composition
Name | Description | Schema |
---|---|---|
type |
TSOrder type (stored in a custom data) |
string |
value |
Cost for this type |
number |
The Depots object stores depots data. They are composed of X,Y coordinates, identity tags and a set of constraints.
If you want to specify depot locations or allow a resource to reload at several depots, use the Depots object to add and configure your depot data. The Depots object contains zero or more elements. If it contains no element, the base location of each resource acts as a depot location. Once a depot is associated with a resource its base location is no longer used as a depot location.
Polymorphism : Composition
Name | Description | Schema |
---|---|---|
TSTimeWindow |
The depot time windows. Use this constraint to specify a depot time window during which the depot is opened. A depot time window is defined by its start time, its end time and days of opening. The start time of a depot time window is the first instant when a resource can enter the depot. Its end time is the last instant when a resource can enter the depot (but it may leave it afterward). You can specify up to 4 depot time windows for each depot. Type : "hh:mm:ss", DateTime. Default : "00:00:00". |
|
allProductsRequired |
Indicates whether a resource must provide all required products or one at least. Set it to True to indicate that a resource must provide all the depot required products. Set it to False to indicate that a resource must provide at least one of the depot required products. Type : boolean Default : True |
boolean |
availability |
Indicates whether a depot is included in the planning process or not. This constraint enables you to easily modify your optimization problem configuration without having to add nor delete your original data. * Set it to True to include a depot element in the planning process. * Set it to False to ignore it: it will not be used in the planning. |
boolean |
deliveryQuantities |
The available quantities of products available at the depot. You can specify up to 24 quantities Type : float array |
number |
excludeResources |
The list of resources excluded from the depot. Use this constraint to specify a list of resources that can not use the depot. Type : string array. Default: Empty array: no resource is excluded from the depot |
string |
fixedLoadingDuration |
The fixed duration for a resource to load at depot. Use this constraint to specify how long takes any resource reload at the depot. You can specify an additional duration according to the quantity to reload, using loadingDurationPerUnit. Type : "hh:mm:ss", DateTime. Default : "00:00:00". Example : tsDepot fixedVisitDuration = "00:30:00" indicates that 30 minutes are needed to load at the depot. tsDepot loadingDurationPerUnit = 120 indicates that 120 seconds are needed to load one unit. If the quantity to reload is 8, for instance, the variable part is 120*8. 16 minutes are required to load at the depot. Total load time = 30 minutes + 16 minutes = 46 minutes accounted for this reload break. |
string |
id |
The unique identifier of the depot |
string |
loadingDurationPerUnit |
The time needed to load a unit of product. This constraint is added to the fixed part of the loading duration: it depends on the total quantity to load. Type : "hh:mm:ss", DateTime, Integer (number of seconds). Default : 0. |
string |
openingDaysList |
The depot days of opening, related to the nth depot time window. Use this constraint to specify the days of operation of a depot referring to a depot time window. It must be related to the tsResourceWorkDays constraint of the resources, as resources work days define the planning period. Depot may be opened on a 64-days long period max, from day 1 to day 64. Type : string value containing days separated with commas (like "1, 2, 5" or "4, 20/05/2010") or intervals (like "1-10", "2=>5" or "22/05/2010=>03/06/2010"). For day intervals, prefer the "=>" separator. 1 is the first day of the planning period, the corresponding date, if any, is defined by the oldest date, for all resources, in the tsResourceWorkDays constraint. No date in the depots days of opening description can precede the first day of the planning period defined by the resources (which is day 1). Default : 1=>64. Example : * Set it to "1" (or "14/05/2010) when a depot is opened on the first day of the planning period. Set it to "1, 2, 4, 5" (or "14/05/2010,15/05/2010,17/05/2010,18/05/2010") if depot may not be visited on the third day of a five-days planning period. * Set it to "1=>5" (or "14/05/2010=>18/05/2010") to define a 5-days long period during which the depot is opened. |
string |
pickupQuantities |
The available space for a product available at the depot. You can specify up to 24 values. Type : float array |
number |
priority |
Depot priority. Use this constraint to specify a priority on the depot. If two depots are nearby the system considers the one with the highest priority **Type : * integer |
number |
requiredProducts |
The list of the products a depots contains. Use this constraint when a depot must be affected to a specific kind of resource: these resources will have to provide the required required to be able to load at the depot. Type : string (as a list of products separated with commas). Default : none |
string |
resourceNames |
Lists the resources that can use the depot. Type : string array. Default : Empty array: no resource can use the depot. Example : Specify ["Vehicle 1","Vehicle 2"] to allow only the resources with tags "Vehicle 1" and "Vehicle 2" to use the depot. |
string |
travelTimeModifier |
Indicates the value of the travel time modifier. When reaching a location situated in a large city, one may want to take into account driving difficulties, such as narrow streets and congestion. The travel time modifier enables to increase the travel times around a location. It is describes by three values. The value by which multiply the travel times around the location (tsDepotTravelTimeModifierValue), the portion of the travel time on which the modifier applies (tsDepotTravelTimeModifierLength) an offset to add to any travel duration leaving or reaching the location (tsDepotTravelTimeModifierOffSet). Example : * Set tsResource travelTimeModifierValue to 1.5, tsResource travelTimeModifierLength to 300 and tsResource travelTimeModifierOffSet to 60 for Resource 1 * Set tsDepot travelTimeModifierValue to 2, tsDepot travelTimeModifierLength to 420 and tsDepot travelTimeModifierOffSet to 0 for Depot 1 If the initial travel duration between Resource 1 and Depot 1 was 1000, one obtains a travel time 360 * 1.5 + 60 + 280 + 420 * 2 + 0 = 1660 Type : float, Default : 1 |
|
x |
longitude WGS84 of depot |
number |
y |
latitude WGS84 of depot |
number |
Polymorphism : Composition
Name | Description | Schema |
---|---|---|
orderOriginalResourceId |
The identity of the resource which visits the customer when evaluating an existing planning. * Use this constraint when you want to evaluate an existing planning. * Use the orderOriginalVisitDay constraint to specify the working day when the visit must be planned. * Use the orderPosition constraint to specify the position of a visit in the tour. Type : string (storing a unique resource tag). Default: : not used |
string |
orderOriginalVisitDay |
Indicates the work day when the resource which visits the customer when evaluating an existing planning. * Use this constraint when you want to evaluate an existing planning. * Use the orderOriginalResourceID to specify the resource which visit the customer. * Use the orderPosition to specify the position of a visit in the tour. Type : integer between 1 and 64 or string representing a date. 1 is the first day of the planning period, the corresponding date, if any, is defined by the oldest date, for all resources, in the tsResourceWorkDays constraint. if the original visit day is in the date format, this date cannot precede the first day of the planning period defined by the resources (which is day 1). Default : not used if the tsOrderOriginalResourceIDis not used, 1 overwise |
string |
orderPosition |
The position of a customer in a resource tour. Use this constraint when you want to evaluate a tour. Type : integer. Default : not used |
number |
Options for optimization request
Polymorphism : Composition
Name | Description | Schema |
---|---|---|
allowBridge |
Allow toll If false, all bridges will be avoided. Default : true. |
boolean |
allowToll |
Allow toll If false, all toll ways will be avoided. Default : true. |
boolean |
allowTunnel |
Allow toll If false, all tunnels will be avoided. Default : true. |
boolean |
balanceType |
Route plans balancing type * NONE : no balancing * ORDERS : balance the number of orders (to be used with balanceValue) * HOURS : balance the route plans duration * QUANTITY : balance the route plans delivered quantity Only available with OTSolver |
|
balanceValue |
Route plans balancing target (to be used with balanceType) Locked route plans are not considered. Only available with OTSolver |
number |
countDepotsInDeliveryCost |
Depot cost configuration for tour delivery cost Specifies how depots stops are counted in tour delivery cost (using PenaltyPerVisit defined on resources). Possible values are : * NONE : depots stops are not counted in tour delivery cost * ALL : each depot stop counts as one visit in tour delivery cost * ALLBUTFIRST : first depot stop is ignored but each following depot stop will count as one visit in tour delivery cost * FIRST : only first depot stop is counted in tour delivery cost Default : NONE. |
|
countVisitCostOnceIfSameLocation |
If true, PenalPerVisit will counted only once in tour delivery cost if several visits at the same location are planned consecutively. |
boolean |
distanceType |
Set the distance unit (meters, feet, km or miles), defaut is meters |
|
evaluation |
Enable this if you just want to evaluate (get cost, distances, etc) a set of tours. Therefore, you must fill the evaluationInfos objects in orders Default : false. (see TSEvaluationInfos) |
boolean |
excludeVisitCostIfMaxAdditionalCost |
Exclude visit delivery cost for visits having the maximum additional cost |
boolean |
fuelCode |
Vehicles fuel type. Possible values are : * diesel * undefined * unleaded |
string |
maxOptimDuration |
maximum optimization time. Default is one minute. Type : Time ("hh:mm" or "hh:mm:ss") or Integer (number of minutes) |
string |
noReload |
Use it to forbid/allow reloads Default : false. |
boolean |
reloadDuration |
Default reload duration Type : Time ("hh:mm" or "hh:mm:ss") or Integer (number of minutes) |
string |
routingMethod |
Routing method Specifies routing method used for travel time and distance matrix computation Possible values are : * TIME : routes minimizing travel time are used * DISTANCE : routes minimizing travel distance are used Default : TIME. |
|
sendResultToWebhook |
Enable result export to webhook If enabled, optimization result will be sent to the webook you defined in Toursolver Cloud configuration. Possible values are : * NONE : result will not be sent automatically when optimization finishes. You will have to call the result or toursResult service to retrieve it. * ORDERS : the "orders" result will be sent to the specified webhook. See OptimResultResult object for details. * TOURS : the "tours" result will be sent to the specified webhook. See OptimToursResult object for details. Default : NONE. |
|
speedPattern |
Speed pattern name Specifies the speed pattern to be used for this optimization. "default_profile" is the internal name for the default speed pattern (its actual name in UI depends on your locale). You can use your own speed pattern (defined in Toursolver UI) but you will have to use its internal name : if you created a pattern called "Paris august speed pattern", its internal name will be "paris_august_speed_pattern". If set to null (or not defined), no speed pattern will be used at all (same speeds for whole day). |
string |
startFromEvaluationInfo |
Enable this if you want the optimization to start from a specified initial configuration. Therefore, you must fill the evaluationInfos Default : false. objects in orders (see TSEvaluationInfos). |
boolean |
teamId |
If you did not specify any resource in your request, all resources defined in your tenant will be used for this optimization. If you specify a team identifier, only the resources of this team will be used. |
string |
useForbiddenTransitAreas |
Whether to use forbidden transit areas Specifies true to use forbidden transit areas, and false to ignore forbidden transit areas If omitted, default to true, but has no effect if no forbidden transit areas are supplied |
boolean |
useOTSolver |
Whether to use OTSolver instead of TSDK OTSolver is the new optimization engine behind Toursolver. It behaves better with big problems (more than 1000 visits). This is still a beta version and all the constraints supported by TSDK are not supported yet but they will be implemented as soon as possible. OTSolver must be enabled for your account before you can use it. |
boolean |
vehicleCode |
Vehicles regulations. Possible values are : * bicycle * bus * car * deliveryIntermediateVehicle * deliveryLightCommercialVehicle * emergencyTruck * emergencyVehicle * intermediateVehicle * lightCommercialVehicle * pedestrian * taxi * truck If not specified, vehicle type defined in UI will be used |
string |
The Order object stores order data.
Order is composed of X,Y coordinates, identity tags, a set of constraints and status reports.
Use the Orders object to specify your orders data. These elements can be considered as deliveries, pick-ups or commercial visits occuring at a specific locations.
The optimization process consists in assigning Orders elements to Resources elements in a way that respects the constraints of every element and minimizes the total cost of the planning.
Polymorphism : Composition
Name | Description | Schema |
---|---|---|
TSTimeWindow |
The visit time windows. Use this constraint to specify a visit time window during which the order can be delivered. A visit time window is defined by its start time, its end time and possible visit days (see tsOrderTimeWindow1_EndTime, tsOrderPossibleVisitDays1). You can specify up to 4 visit time windows for a customer. Type : array of time windows Default : "00:00:00". Example : A customer can only be delivered: * * on Monday from 11:00:00 to 12:00:00 AM and from 04:00:00 to 05:00:00 PM, * on Tuesday, Wednesday, Thursday from 08:00:00 to 09:00:00 AM and from 04:00:00 to 05:00:00 PM, * on Friday from 08:00:00 to 09:00:00 AM. Its visit time windows will be specified as follows: * first time window StartTime = "08:00:00", EndTime = "09:00:00", first set of possible days = "2=>5", * second time window StartTime = "11:00:00", EndTime = "12:00:00", second set of possible days = 1, * third time window StartTime = "16:00:00", EndTime = "17:00:00", third set of possible days = "1=>4". |
|
active |
Indicates whether the order should scheduled or not Default : True. |
boolean |
allSkillsRequired |
Indicates whether a resource must provide all required skills or one at least. * Set it to True to indicate that a resource must provide all the customer required skills. * Set it to False to indicate that a resource must provide at least one of the customer required skills. Default : True. |
boolean |
courierPenalty |
The cost of the order delivered by an independant transport device. Use this constraint when an order can be delivered independantly to specify the cost of the device. The solver engine will assign it to a courier device or integrate it in a tour according to the least cost. Type : float. Default : not used. |
number |
customDataMap |
Private feature data. Use this feature when you need to keep accessible private data about customers. For instance if you need to export the address of an element in a planning report, store it there. These informations can also be exported to the mobile app. max 50 fields Default : empty. |
object |
customerId |
string |
|
delayPenaltyPerHour |
The penalty per hour for being late at a customer. Use this constraint to allow a smarter control, with respect to time windows, than with the use of the tsOrderPunctuality constraint. Type : float. Default : not used. |
number |
email |
string |
|
evaluationInfos |
first order assignment (specifying resource, day and position in route). Use it to compare optimization result with a previous optimization Warning : used only if startFromEvaluationInfo is set to true in options. |
|
fixedVisitDuration |
The fixed part of the total time spent visiting a customer. Use this constraint to specify the minimum time spent at a customer’s. Use it to store the time needed by a vehicle to park, for instance, or the time planned for a commercial meeting. Type : Time ("hh:mm" or "hh:mm:ss") or Integer (number of minutes). Default : not used. Example : * tsOrderFixedVisitDuration = "00:30:00" indicates that the visit will be 30 minutes long. * tsOrderUnloadingDurationPerUnit = 120 indicates that 120 seconds are necessary to unload one unit. With a tsOrderQuantity equal to 8, for instance, the variable part is 120*8 (960 seconds or 16 minutes) to unload the customer ordered quantity. * Total delivery time = 30 minutes + 16 minutes = 46 minutes accounted for the customer delivery. |
string |
frequency |
The visit occurrence within a defined period. Use this constraint to plan multiple visits at a customer during a period. Type: string value describing the number of visits over a period. Default: not used. Example : Frequency = "3/5" means a customer must be visited 3 times within a 5-days long period. The solver engine will create and optimize routes respecting an optimal duration between consecutive visits. Thus, back to the example, the computed period is 5/3 rounded = 2. The best solution will respect, as far as possible, a 2-days long period between each visit (ex: day1, day3, day5 is a good solution). |
string |
getNotifications |
Boolean.True if a visit can receive notification email/sms |
boolean |
id |
The unique identifier of the order |
string |
label |
string |
|
minDuration |
The min duration of the visit that enables partition. When the total duration of an order is very long, you may want to part it into multiple consecutive visits. First use this constraint to specify a duration threshold from which visit can be cut into multiple parts. Then use the tsOrderMinPartDuration to specify the min duration of one part. Type : Time ("hh:mm" or "hh:mm:ss") or Integer (number of minutes). Default : not used. |
string |
minPartDuration |
The min duration of a part of a split visit. When the total duration of an order is very long, you may want to part it into multiple consecutive visits. First use the tsOrderMinDuration to specify a duration threshold from which the visit can be cut into multiple parts. Then use this constraint to specify the min duration of one part. The visit is split into parts of the set duration, and eventually a bigger one. Type : Time ("hh:mm" or "hh:mm:ss") or Integer (number of minutes). Default : not used. |
string |
phone |
string |
|
possibleVisitDaysList |
The possible visit days related to each visit time window. Use this constraint to specify the possible visit days of a customer referring to a visit time window. It must be related to the tsResourceWorkDays constraint of the resources, as resources work days define the planning period. You can plan visits on a 64-days-long period max. Type : array of string values containing visit days separated with commas (like "1, 2, 5" or "4, 20/05/2010") or intervals (like "1-10", "2=>5" or "22/05/2010=>03/06/2010"). For day intervals, prefer the "=>" separator. Be carrefull, if the separator of date is - then "1-5" corresponds to May the 1st of the current year. 1 is the first day of the planning period, the corresponding date, if any, is defined by the oldest date, for all resources, in the tsResourceWorkDays constraint. No date in the possible visit days description can precede the first day of the planning period defined by the resources (which is day 1). Default: 1=>64. You can set up to 4 sets of visit days in this array. If you define several time windows, each time window will apply to corresponding set of possible days : first time window applies to first possible days set, second time window applies to second possible days set, etc. Example : * Set it to "1" (or "14/05/2010) when a customer must be visited on the first day of the planning period. * Set it to "1, 2, 4, 5" (or "14/05/2010,15/05/2010,17/05/2010,18/05/2010") if the customer cannot be visited on the third day of a five days planning period. * Set it to "1=>5" (or "14/05/2010=>18/05/2010") to define a 5-days long period during which the customer can be visited. |
string |
punctuality |
The priority for a customer to be delivered on time. Use this constraint to introduce different priority levels for the respect of visit time windows (when defined). Specify a value from 1 to 5 to set the priority: customers with a punctuality set to 5 will have less risk of delayed deliveries than a customer with a punctuality set to 1. You can specify more precisely punctuality requirements to enforce delay control by using the tsOrderDelayPenaltyPerHour constraint instead of the tsOrderPunctuality constraint. Type : integer value from 1 to 5. Default : 1. |
number |
quantity |
The requested product quantities for an order. Use this constraint to specify the product quantities ordered by a customer, for instance. Up to 24 quantities can be used to order different products. Useless when planning commercial tours. Type : float array (maximum of 3 significant digits after decimal separator). Default : 0 Max : 2,147,483. Example : * Use this constraint to store the number of ordered packages, when working with packages. * Use this constraint to store the number of ordered liters, when working with liquids. * Use multiple dimensions when working with multiple products: when delivering fuels for instance, you will use as many dimensions as types of fuels Warning : The quantity constraint of the Orders elements must be related to the corresponding capacity constraint of the Resources elements: thus, an order will not be planned whenever no resource with the related capacity has been defined. |
number |
requiredSkill |
The list of the skills a customer requires to be visited. Use this constraint when an order must be affected to a specific kind of resource: these resources will have to provide the required skills to be able to visit the customer. Type : string array. Default : none. Example : * Specify the word "Maintenance" as a required skill for a maintenance visit. Only the resources providing the "Maintenance" skill can perform the visit. * Specify "Small vehicle" as a required skill for a customer living down town. |
string |
resource |
The identities of the resources which must not deliver a customer. Use this constraint when you want to prevent some customers from being delivered by specific resources. |
string |
resourceCompatibility |
Value for compatibility with resources. If the order has a compatibility constraint value, a resource is compatible with the order if its compatibility value is either non-existent either larger or equal to the order’s one. See tsResourceOrderCompatibility. Example : * Set tsOrderResourceCompatibility to 254.18 and tsResourceOrderCompatibility to 260.12: order and resource are compatible * Set tsOrderResourceCompatibility to 254.18 and tsResourceOrderCompatibility to 200: the order can not be affected to the resource * Set tsOrderResourceCompatibility to 254.18 and tsResourceOrderCompatibility empty: order and resource are compatible * Set tsOrderResourceCompatibility empty and tsResourceOrderCompatibility to 260.12: order and resource are compatible Type : double Default : -1 |
number |
sequenceNumber |
number |
|
travelTimeModifier |
Indicates the value of the travel time modifier. When reaching a location situated in a large city, one may want to take into account driving difficulties, such as narrow streets and congestion. The travel time modifier enables to increase the travel times around a location. It is describes by three values. The value by which multiply the travel times around the location (tsOrderTravelTimeModifierValue), the portion of the travel time on which the modifier applies (tsOrderTravelTimeModifierLength) an offset to add to any travel duration leaving or reaching the location (tsOrderTravelTimeModifierOffSet). Example : * Set tsOrderTravelTimeModifierValue to 1.5, tsOrderTravelTimeModifierLength to 300 and tsOrderTravelTimeModifierOffSet to 60 for Order 1 * Set tsOrderTravelTimeModifierValue to 2, tsOrderTravelTimeModifierLength to 420 and tsOrderTravelTimeModifierOffSet to 0 for Order 2 If the initial travel duration between Order 1 and Order 2 was 1000, one obtains a travel time 360 * 1.5 + 60 + 280 + 420 * 2 + 0 = 1660 Type : float Default : 1 |
|
tsOrderBefore |
string |
|
tsOrderBeforeMaxTimeSpacing |
string |
|
tsOrderBeforeMinTimeSpacing |
string |
|
tsOrderFixed |
If true force the use of the specified day, resource and start time |
boolean |
tsOrderLastVisit |
The number of days before the beginning of the planning the last visit belonging to the order has been performed Use this constraint in case of a frequency order to specify from how many days the last visit was performed before starting the current planning. The default value indicates this constraint is to be unused in the planning. Type : negative integer Default : 0 Max : -2,147,483. Example : If tsOrderLastVisit = -2, the last visit of the same order has been performed two days ago. Warning : if the number of occurences of the frequency is more than one, the constraints tsOrderLastVisit and tsOrderMinimumSpacing are not considered. |
number |
tsOrderMaximumSpacing |
The maximum number of days required between two visits of a same order. Use this constraint in case of frequency order to specify how many days at most should be left between two visits of the order. Type : integer Max : 2,147,483. |
number |
tsOrderMinimumSpacing |
The minimum number of days required between two visits of a same order. Use this constraint in case of frequency order to specify how many days at least should be left between two visits of the order. Type : integer Default : 0 Max : 2,147,483. Warning : if the number of occurences of the frequency is more than one, the constraints tsOrderLastVisit and tsOrderMinimumSpacing are not considered. |
number |
type |
The type of visit at a customer. * 0 (Delivery): the resource will delivere related quantities. * 1 (PickUp): the resource will pick-up related quantities. * 2 (DeliveryFirst): the resource will not mix deliveries and pick-ups in a same rotation. It is possible to mix pickups and 0 type deliveries in the same rotation. However, the delivered products will come from the depot and the pickup products will be unloaded at the depot. No product delivered to a customer can come from a pickup at another customer’s. Type : Integer. Default : 0 (Delivery). |
number |
unloadingDurationPerUnit |
The time needed to deliver one unit of product. Use this constraint when the time spent at a customer depends on the quantity to deliver. It is the time needed to unload one unit of the quantity stored in the customer tsOrderQuantity constraint. Type : Time ("hh:mm" or "hh:mm:ss") or Integer (number of minutes). Default : not used. |
string |
wholeVisitInTimeWindow |
Whole visit ends before time window end. Use this constraint if you want that a visit ends before the end of the time window. Default : false. |
boolean |
x |
longitude of order location |
number |
y |
latitude of order location |
number |
Polymorphism : Composition
Name | Description | Schema |
---|---|---|
duration |
Duration Type : Time ("hh:mm" or "hh:mm:ss") or Integer (number of minutes). |
string |
end |
maximum end time Type : Time ("hh:mm" or "hh:mm:ss") |
string |
start |
minimum start time Type : Time ("hh:mm" or "hh:mm:ss") |
string |
Details of a stop within a resource tour.
Polymorphism : Composition
Name | Description | Schema |
---|---|---|
dayId |
day of the stop |
string |
resourceId |
Assigned resource identifier |
string |
stopDriveDistance |
The drive distance from the previous to the current stop. |
number |
stopDriveTime |
The drive time from the previous to the current stop. Type : Time ("hh:mm" or "hh:mm:ss") |
string |
stopDuration |
The duration of the stop. Type : Time ("hh:mm" or "hh:mm:ss") |
string |
stopElapsedDistance |
The tour cumulated driven distance at the stop. |
number |
stopId |
the ID of the stop or order |
string |
stopPosition |
The position of the stop in the resource tour. |
number |
stopStartTime |
The time the stop starts at. Type : Time ("hh:mm" or "hh:mm:ss") |
string |
stopStatus |
The status of the stop. An order can be on time, late, waited, impossible (non compliant). It can also be a courier service delivery and not planned. See StopStatusConstants for more information about stop status. Type : integer. * 0 = OnTime: The stop begins into the specified visit time window. * 1 = Late: The stop begins after the specified visit time window. * 2 = Waited: The resource waits at the stop for the specified stop start time. * 3 = Impossible: The stop cannot be planned. * 4 = BadDay: The stop is planned without respect of frequency. * NotPlanned: The courier service is in charge of a stop or the stop is not included in the planning process. * BadPrevious : When the visits are split, the parts should follow one another. This status is that of a part following another visit instead of the previous part of the split visit. |
number |
stopType |
The stop type A tour is composed of stops, which can be either customers visits or breaks, like reload breaks, lunch breaks, or even night breaks. StopTypeConstants are * 0 = Visit: The stop is an element of the Orders object. * 1 = Start: The stop is the initial stage (departure) of the tour, occurring at the resource’s start location. * 2 = End: The stop is the the last stage (arrival) of the tour, occurring at the resource’s stop location. * 3 = EndBeforeOvernight: The stop is the the last stage (arrival) of the tour, occurring where the resource stopped for the night. * 4 = ReloadBreak: The stop is a reload break within the tour, occurring at a depot location. * 5 = LunchBreak: The stop is the lunch break within the tour, occurring anywhere between two other located stops. * 6 = RestBreak: The stop is a rest break within the tour, occurring anywhere between two located stops. * 7 = WaitBreak: The stop is a wait break within the tour, occurring before a visit. * 8 = StartAfterOvernight: The stop is the last stage (arrival) of the tour, it occurs where the resource stopped for the night. tsStopDriveDistance * 9 = Briefing: The stop is a briefing break within the tour, occurring right after the departure of the tour. * 10 = DeBriefing: The stop is a wait break within the tour, occurring right before the arrival of the tour. |
number |
stopX |
The X coordinate of the stop. |
number |
stopY |
The Y coordinate of the stop. |
number |
The Resources object stores the collection of the elements which will perform deliveries, pick-ups, commercial visit, etc.
Each element can be seen as a driver/vehicle pair and their related driving and working constraints.
It is composed of an identity tag, and location coordinates (base or depot, departure, arrival location). Eventually, each element can be configured through a set of constraints which stores information like capacity, driver work time, penalties and so on.
Polymorphism : Composition
Name | Description | Schema |
---|---|---|
additionalCostOperator |
Operator used to compute additional cost (see toursResult object) Possible values are : * SUM : tour additional cost will be the sum of additional costs of planned orders * MAX : tour additional cost will be the maximum value of additional costs of planned orders * MIN : tour additional cost will be the minimum value of additional costs of planned orders * AVERAGE : tour additional cost will be the average of additional costs of planned orders |
|
additionalCostOrderCustomDataName |
Name of TSOrder customData that will contain the TSOrder type used for additional cost computation (see toursResult object) |
string |
additionalCosts |
List of additional cost (cost per order type) |
|
available |
Indicates whether a resource is included in the planning process or not. This constraint enables you to easily modify your optimization problem configuration without having to add nor delete original data. * Set it to True to include a resource element in the planning process. * Set it to False to ignore it: it will not be used in the planning. Type : Boolean. Default : not used. |
boolean |
avgConsumption |
Average consumption of the resource. Use this constraint to specify the average consumption of the resource. This consumption must be defined in liters per 100 distance unit (km or miles) Default : The consumption indicated in the VehicleProfile.Consumption property. |
number |
briefingDuration |
An additional duration applied before the tour starts. Use this constraint to specify an additional duration before the resource begins the tour. For instance, to brief drivers before they leave or to simulate an initial vehicle loading time (no depot). Type : "hh:mm:ss", DateTime. Default : "00:00:00". |
string |
capacity |
The total product capacity a resource can carry. Use this constraint to specify the amount of product a resource can deliver or pick-up. It must be linked with the customers related quantity constraint. 23 more dimensions can be used in order to specify various products. They must be linked with the customers related dimensions. Type : float (maximum of 3 significant digits after decimal separator). Default: None. Max : 2,147,483. Example : * Use it to store the total number of packages a resource can deliver before reloading, when working with packages. * Use it to store the total number of litres a resource can deliver before reloading, when working with liquids. * Use multiple capacity dimensions when working with multiple products: when delivering fuels, you will use as many capacities as types of fuels. |
number |
customDataMap |
Private custom data. Use this feature when you need to keep attributes values of your own into the optimization context. For instance if you need the address of an element, store it there. |
object |
dailyWorkTime |
The maximum resource work duration over a day. Use this constraint to specify the maximum daily work duration (unless overtime periods have been defined). If the dailyWorkTime constraint is not set to a value, default daily work time is computed from resource time window and lunch duration (workStartTime, workEndTime and lunchDuration). Type : "hh:mm:ss", DateTime. Default : not used. |
string |
debriefingDuration |
An additional duration applied at the end of the tour. Use this constraint to specify an additional duration after the resources stops at the end location. For instance, to debrief drivers after their tour or to account an ultimate vehicle unloading time, or a parking time. Type : "hh:mm:ss", DateTime. Default : "00:00:00". |
string |
driveRestAtCustomer |
Indicates whether or not time spent at customer during deliveries can be considered as rest break. * Set it to True if a visit can be considered as a rest break, as soon as its duration is equal or higher than the legalMinRestDuration constraint. * Set it to False if not. Type : Boolean. Default : False. |
boolean |
driveRestAtDepot |
Indicates whether time spent at depot during a reload break can be considered as drive break or not. Use this constraint to take into account drive time legislation in your planning results. * Set it to True if load breaks can be considered as drive breaks, as soon as their duration is equal or higher than the legalMinRestDuration constraint. * Set it to False if not. Type : Boolean. Default : False. |
boolean |
endX |
longitude of resource arrival Specify it only if arrival and start are not the same. |
number |
endY |
latitude of resource arrival Specify it only if arrival and start are not the same. |
number |
extraTravelPenalty |
The costs for a resource of driving for one distance unit. |
|
fixedLoadingDuration |
The fixed duration of the resource load break. Use this constraint to specify how long takes a resource reload at depot. You can specify an additional duration according to the quantity to reload, using loadingDurationPerUnit. Type : "hh:mm:ss", DateTime. Default : "00:00:00". Example : * fixedVisitDuration = "00:30:00" indicates that 30 minutes are needed to load the resource. * loadingDurationPerUnit = 120 indicates that 120 sec are needed to load one unit. If the quantity to reload is 8, for instance, the variable part is 120*8. 16 minutes are required to load the resource. * Total load time = 30 minutes + 16 minutes = 46 minutes accounted for this reload break. |
string |
fixedUnloadingDuration |
The fixed time needed for the resource to deliver/pick-up at the customer’s place. This fixed resource’s unloading duration is added to the resource’s unloading duration depending on the quantity to deliver/pick-up and to the order’s unloading duration depending on the quantity to deliver/pick-up. See also tsResource unloadingDurationPerUnit and tsOrder unloadingDurationPerUnit. Example : * Set tsOrderQuantity to 3. * Set tsOrder unloadingDurationPerUnit to 2 mn and tsResource fixedUnloadingDuration and tsResource unloadingPerUnit to 0 or empty: the variable part of the order is 6 mn * Set tsOrder unloadingDurationPerUnit to 2 mn and tsResource fixedUnloadingDuration to 10 mn and tsResource unloadingPerUnit to 0 or empty: the variable part of the order is 10 mn * Set tsOrder unloadingDurationPerUnit to 2 mn and tsResource fixedUnloadingDuration empty and tsResource unloadingPerUnit to 1 mn: the variable part of the order is 3 mn Type : "hh:mm:ss", DateTime. Default : "" Warning : the fixed/per unit unloading duration for resource is not compatible with the orders constraints: partition and whole visit in time window. Hence if one of the constraint at least tsResource fixedUnloadingDuration and tsResource unloadingDurationPerUnit is non null, partition and whole visit in time window are disabled. |
string |
fuelCode |
Vehicles fuel type. Possible values are : * diesel * undefined * unleaded |
string |
fuelType |
The fuel type of the resource. Use this constraint to specify the fuel type of the resource. Available fuel types are : * 0: Unknown fuel type * 1: No fuel type (pedestrian) * 2: Diesel * 3: Unleaded fuel * 4: LPG Type : Integer. Default : The fuel type indicated in the VehicleProfile.FuelType property. |
number |
globalCapacity |
Global capacity for a resource. This constraint unables to set a maximum capacity on a resource, whatever product is carried. If both global capacity and capacity per product are to be used, set True for the value of useAllCapacities. Type : Float Default : None Max : 2,147,483. Example : Set globalCapacity = 15 and useAllCapacities = False. The global capacity only is considered: the vehicle can carry 15 quantities of products, whatever product is to be carried. |
number |
id |
The unique identifier of the resource. This id can not contain special characters like = or : |
string |
legalDailyDriveDuration |
The legal daily duration a resource can drive before having a rest break. Use this constraint to take into account drive time legislation in your planning results. Specify the rest duration in the legalDailyRestDuration: rest breaks occur as soon as the resource has driven the legal daily driving duration or has completed its daily work time. Type : "hh:mm:ss", DateTime. Default : not used. Example : legalDailyDriveDuration = "09:00:00", legalDailyRestDuration = "11:00:00". The resource can cumulate a 9-hours daily drive time before having to rest during 11 hours. |
string |
legalDailyRestDuration |
The legal rest duration a resource must have after the daily max drive duration. Use this constraint to take into account drive time legislation in your planning results. Rest breaks occur as soon as the resource has driven the legal max daily duration or has complete its daily work time. The use of both legalDailyDriveDuration and legalDailyRestDuration implies that the start and end time of tours are no longer defined by the workStartTime and workEndTime constraints, but may vary as long as the legalDailyRestDuration constraint is respected. Type : "hh:mm:ss", DateTime. Default : not used. |
string |
legalDriveRestDuration |
The resource break duration after max drive duration. Use this constraint to take into account drive time legislation in your planning results. Type : "hh:mm:ss", DateTime. Default : not used. |
string |
legalMaxDriveDuration |
The legal max duration a resource can drive without a break. Use this constraint to take into account drive time legislation in your planning results. Type : "hh:mm:ss", DateTime. Default: : not used. Example : * legalMaxDriveDuration = "04:30:00", legalDriveRestDuration = "00:45:00". The resource can drive for 4 hours and 30 minutes before having a 45 minutes break. Then it can start driving again for 4 hours and 30 minutes???etc. * If added driveRestAtCustomer = True and legalMinRestDuration = "00:15:00", rest time is cumulated as soon as customer visit duration is equal or higher than the specified min rest duration. If the 45 minutes rest break has not occured when the resource has driven for 4 hours and 30 minutes, it must stop to complete the break. Otherwise, it can drive again for 4 hours and 30 minutes. |
string |
legalMinRestDuration |
The minimum duration a resource breaks for it to be considered as a drive break. Use this constraint to take into account drive time legislation in your planning results. When breaks occur at customer or at depot, they are considered as drive breaks if their duration is equal or higher than the specified min rest duration. Type : "hh:mm:ss", DateTime. Default: : not used. |
string |
loadBeforeDeparture |
Indicates whether a resource must load before starting a tour or not. * Set this constraint to True to insert a load break at depot before the tour starts. * Set it to False to consider the vehicle loaded. Type : Boolean. Default: : False. |
boolean |
loadOnReturn |
Indicates whether a resource must reload after a tour or not. * Set this constraint to True to insert a load break at depot after the tour ends. * Set it to False to not reload the vehicle. Type : Boolean. Default: : False. |
boolean |
loadingDurationPerUnit |
The time needed to load a unit of product. This constraint is added to the fixed part of the loading duration: it depends on the total quantity to load. Type : "hh:mm:ss", DateTime, Integer (number of seconds). Default: : 0. |
string |
lunch |
The lunch break Default: : no lunch break |
|
maxNightsOutPerJourney |
The number of nights a resource can spend out to perform deliveries before coming back to base. Use this constraint to enable night breaks trip: it will store how many days a resource can drive away from depot. Unless the vehicle needs to reload, it will not come back before. Type : integer. Default: : not used. Example: maxNightsOutPerJourney = 4, workDays = 1=>5. The resource can perform deliveries during 5 days (and 4 nights) without coming back to depot. Starting on day 1, it must come back to depot on day 5. |
number |
maximumDistance |
The maximum distance the resource should travel per day. Use this constraint to specify the distance the resource should not exceed in one day Type : integer Default : -1 (no limit) |
number |
maximumReloads |
Value for maximum number of reloads per day. |
number |
maximumReloadsPenalty |
Value of the penalty if the resource exceeds the maximum number of reloads per day. If the resource exceeds the maximum number of reloads per day, it will be penalized by the maximum reloads penalty multiplied by the number of reloads' overtaking. The default value is 1024 if the constraint maximumReloads is set. See also maximumReloads. |
number |
maximumVisits |
The maximum number of visits the resource can perform in one day. Type : integer Default : -1 (no limit) Max : 2,147,483. |
number |
minDriveDuration |
The minimum laps of time between 2 consecutive visits. Use this constraint to specify a minimum drive time accounted when consecutive visits are very close, in order to compute a realistic timing. Type : "hh:mm:ss", DateTime. Default: : not used. |
string |
minimumQuantity |
Value for minimum quantity to deliver. If the resource has a non null minimum quantity to deliver constraint value, the resource can visit on order only if the quantity to be picked-up or delivered at this order is higher than the constraint value. *Example : * * set order quantity to 3 and resource minimumQuantity to 2 : resource might visit the order * set order quantity to 3 and resource minimumQuantity to 5 : resource can not visit the order Type : float |
number |
mobileLogin |
Mobile login to be specified only if you need to be able to export the optimization result to operation planning from TsCloud GUI. If you trigger operational planning export from the API, you will still need to specify the mapping between resource name and login. |
string |
nightPenalty |
The night cost of a resource when planning night breaks. Use this constrainte to specify how much a night out costs (lunch, bed, breakfeast???) for a resource when night breaks are allowed. Type : float. Default: : 0 |
number |
noReload |
Constraint providing resource to reload at depot during a tour. If none of the constraints loadBeforeDeparture and loadOnReturn is activated, the resource is never loading at depot. If one of these constraint is activated the resource is loading once per tour, either at the beginning of the tour or at the end of it. If both constraints are activated then the resource is loading twice a tour, at the beginning and at the end. With standard solver only : solver always works with solution cost comparison, so it may allow reloads even if you set noReload to true if the solution cost is really lower. The only way to totally prevent reloads is to set fixedLoadingDuration to a very long duration (20:00:00 for instance). The solver will warn you about this long duration but will not add reloads to the tours. Caution : Don’t do this if you are using loadOnReturn or loadBeforeDeparture Default : False |
boolean |
nonUsePenalty |
A cost paid for NOT using a resource in the computed planning. Use this constraint to penalize the fact that an available resource is not used in the planning. It proves usefull when you must use all the resources in the Resources collection: you will prevent the solver from optimizing the number of resources, as using them would be too expensive a solution. Type : float. Default: : not used. Example : Use it to specify parking taxes when a vehicle performs no tour. |
number |
openDistanceStart |
boolean |
|
openDistanceStop |
boolean |
|
openStart |
Indicates whether or not a tour evaluation starts from the resource start location or from the first customer’s place. * Set it to True to begin the tour at the first customer (no cost will be computed between the resource start location and the first customer). * Set it to False to begin the tour at the resource start location. Type : Boolean. Default: : False. |
boolean |
openStop |
Indicates whether or not a tour evaluation ends at the last customer’s place or at the resource end location. * Set it to True to finish the tour at the last customer location (no cost will be computed between the last customer and the resource end location). * Set it to False to finish the tour at the resource end location. Type : Boolean. Default: : False. |
boolean |
openTimeStart |
boolean |
|
openTimeStop |
boolean |
|
optimumStartTime |
Adapts the resource start time to the best solution. * Set this constraint to False to start the tour at the time indicated by the workStartTime constraint. * Set this constraint to True to optimize the resource start time and enable the use of the dailyWorkTime constraint. Notice that, in both cases, the tour will not start before the time stored in the workStartTime constraint and that the use of the weeklyWorkTime constraint is enabled. Type : Boolean. Default: : False. |
boolean |
otherWorkEndTime |
The end time of the resource work time window for the "other working days" (see otherWorkDaysList). If you defined other working days, use this constraint to specify the time at which the tour must end. These times can be adjusted using the optimumStartTime parameter. You can define up to 3 different end times here, corresponding to the different "other working days" slots. Type : List of "hh:mm:ss", DateTime. Example : ["18:00:00","19:00:00] |
string |
otherWorkStartTime |
The start time of the resource work time window for the "other working days" (see otherWorkDaysList). If you defined other working days, use this constraint to specify the time at which the tour must start. These times can be adjusted using the optimumStartTime parameter. You can define up to 3 different start times here, corresponding to the different "other working days" slots. Type : List of "hh:mm:ss", DateTime. Example : ["08:00:00","09:00:00] |
string |
otherWorkingDay |
Other working days (see workingDays) You can define up to 3 different working days slots. If you do so, you can then specify distinct work start and end times with otherWorkStartTimes and otherWorkEndTimes. Type : List of string (see workingDays format) Example : ["2","3=>5"] |
string |
overnightMinDriving |
The max duration a resource can drive to go back to base at the end of a tour when working with night breaks. Use this constraint when a resource can end a tour at base instead of having a night break on the road. Type : "hh:mm:ss". Default: : not used. |
string |
overtimeDuration |
The duration of the resource overwork periods. (max 2 periods) Use this constraint when you need to define 2 different overwork periods with regard to daily work time and their related surcharge. No overwork period can be defined with regard to weekly work time. Type : "hh:mm:ss", DateTime. Default: : not used (no second overtime period). Example : workPenalty = 10, first overtime duration = "02:00:00", first overtime penalty = 5,second overtime duration = "01:00:00", second overtime penalty = 10. The cost of the resource during the daily working time is 10 euros per hour. The resource can work during 3 more hours and each overworked hour will cost 10 + 5 euros for 2 hours and 10 + 10 euros for the last hour. |
string |
overtimePenalty |
A surcharge for a resource’s overwork period (max 2 periods). Use this constraint to specify additional cost to workPenalty as overwork time. You can define up to 2 overwork periods with regard to daily work time and their related surcharge. No overwork period can be defined with regard to weekly work time. Type : float. Default: : not used. Example : workPenalty = 10, first overtime duration = "02:00:00", first overtime penalty = 5. The cost of the resource during the daily working time is 10 euros per hour. The resource can work during 2 hours after the daily working time and each overworked hour will cost 15 (10 + 5) euros. |
number |
payWholeDay |
Indicates whether or not a whole work day cost is computed as soon as a resource works even a few hours. * Set this constraint to True to account a whole day cost. * Set it to False to account only effective worked hours. Type : Boolean. Default: : False. |
boolean |
penaltyPerVisit |
An additional fixed cost applied each time the resource performs a visit. Use this constraint when the cost of a resource may vary according to the number of visits it performs. Type : float. Default: : 0. |
number |
providedProducts |
The list of products provided by a resource. This constraint is linked with tsDepot requiredProducts constraint: a depot with a required product can only be visited by a resource providing it. Type : string as a list of products separated with commas. Default : not used. Example : Specify "Oxygen" in the resource can provide oxygen. |
string |
providedSkills |
The list of characteristics provided by a resource. This constraint is linked with the same order constraint: a customer with a required skill can only be delivered by a resource providing it. Type : string as a list of characteristics separated with commas. Default: : not used. Example : * Specify "Maintenance" in the provided skills of a resource designed to perform maintenance visits type. * Specify "Small vehicle" to the provided skills of a resource able to perform downtown visits. |
string |
speedAdjustment |
A factor to increase or decrease the vehicle speed. Whenever users observe a significant gap between estimated speeds and the real ones, they can adjust them by using this factor. It is expressed as a percentage of the used speed. Type : float. Default: : not used. Example : * speedAdjustment = 110: resource speeds will be 10% higher than the used speeds. * speedAdjustment = 80: resource speeds will be 20% lower than the used speeds. |
number |
startTravelTimeModifier |
travel time modifier associated with the start location of the resource |
|
startX |
longitude of resource start (and arrival if no endX provided) |
number |
startY |
latitude of resource start (and arrival if no endY provided) |
number |
stopTravelTimeModifier |
travel time modifier associated with the stop location of the resource |
|
tomTomWebFleetEnabled |
boolean |
|
tomTomWebFleetIdentifier |
string |
|
travelPenalty |
The cost for a resource of driving for one distance unit. Use this constraint to specify the average resource taxes (gazoline, wear,???) when driving one distance unit. Type : float Default : 1.5 Example : if travelPenalty = 0.5 (euro per distance unit) and the driven distance is about 100 unit (km or miles), the total distance cost is 0,5 * 100 = 50 euros. |
number |
travelTimeModifier |
travel time modifiers When reaching a location situated in a large city, one may want to take into account driving difficulties, such as narrow streets and congestion. The travel time modifier enables to increase the travel times around a location. It is describes by three values. The value by which multiply the travel times around the location travelTimeModifierValue), the portion of the travel time on which the modifier applies (travelTimeModifierLength) an offset to add to any travel duration leaving or reaching the location (travelTimeModifierOffSet). Example : * Set travelTimeModifierValue to 1.5, travelTimeModifierLength to 300 and travelTimeModifierOffSet to 60 for Resource 1 * Set travelTimeModifierValue to 2, travelTimeModifierLength to 420 and travelTimeModifierOffSet to 0 for Order 1 If the initial travel duration between Resource 1 and Order 1 was 1000, one obtains a travel time 360 * 1.5 + 60 + 280 + 420 * 2 + 0 = 1660 |
|
unloadingDurationPerUnit |
the time needed to the resource to deliver/pick-up one unit of product at the customer’s place. This resource’s duration is added to the fixed resource’s unloading duration and to the order’s unloading duration depending on quantity to deliver/pick-up. See also tsResource fixedUnloadingDuration and tsOrder unloadingDurationPerUnit. Example : * Set tsOrderQuantity to 3. * Set tsOrder unloadingDurationPerUnit to 2 mn and tsResource fixedUnloadingDuration and tsResource unloadingPerUnit to 0 or empty: the variable part of the order is 6 mn * Set tsOrder unloadingDurationPerUnit to 2 mn and tsResource fixedUnloadingDuration to 10 mn and tsResource unloadingPerUnit to 0 or empty: the variable part of the order is 10 mn * Set tsOrder unloadingDurationPerUnit to 2 mn and tsResource fixedUnloadingDuration empty and tsResource unloadingPerUnit to 1 mn: the variable part of the order is 3 mn Type : "hh:mm:ss", DateTime. |
string |
useAllCapacities |
Determines if both global capacity and capacities per product should be considered in the optimization or only global capacity. Type : Boolean Default : False Example : Set globalCapacity = 15 and useAllCapacities = False. The global capacity only is considered: the vehicle can carry 15 quantities of products, whatever product is to be carried. |
boolean |
useInPlanningPenalty |
Penalty value if the resource is used in the planning. Use this constraint to specify the penalty if the resource is used at least one day in the planning Type : float Default : 0 |
number |
usePenalty |
A cost paid for using the resource in the computed planning. Use this constraint to ponderate the cost of using a resource element of the Resources collection, when working with rented vehicle for instance. You can use it as well to reduce the number of resources used to perform the deliveries. Type : float. Default: : not used. Example : Add the cost of use to the distance and hourly costs when working with a service provider. The solver, aiming at cost reduction, will try to eliminate this resource first, as it is the most expensive. |
number |
vehicleCode |
Vehicles regulations. Possible values are : * bicycle * bus * car * deliveryIntermediateVehicle * deliveryLightCommercialVehicle * emergencyTruck * emergencyVehicle * intermediateVehicle * lightCommercialVehicle * pedestrian * taxi * truck If not specified, vehicle type defined in UI will be used Only new solver can handle optimization with several types of vehicle. If you use standard solver, you should specify the vehicle code only in the options object. |
string |
weeklyWorkTime |
The maximum resource work duration over a week. Use this constraint to specify the maximum weekly work duration. Weeks are defined as follows: * year’s week, from monday to sunday, if a date has been specified in the workDays constraint * days 1 to 7 are the days of the first week and the second week start on day 8 if no date has been specified in the workDays constraint. No over work with regard to the weekly work duration is allowed. Type : "hh:mm:ss", DateTime. Default: : "168:00:00". |
string |
workEndTime |
The end time of a resource work time window. Use this constraint to specify the time at which the tour must be over or the daily work duration. * If the optimumStartTime parameter is set to True and the dailyWorkTime or weeklyWorkTime constraint value is set by user, the tour cannot finish later than the value of the workEndTime parameter, whatever overtime may be allowed by the overtime1_Duration and overtime2_Duration constraints. * If the optimumStartTime parameter is set to True and the dailyWorkTime constraint value is not set, the end time of the tour can be adjusted to match the begining of the work time window. In this case, this parameter is used only to compute the resource daily work time and the tour can finish at midnight. * If the optimumStartTime parameter is set to False, then this parameter is used to compute the resource daily work time and the tour can finish no later than the specified end time plus the values of the first overtime duration and the second overtime duration constraints. If the daily work duration is specified by the workEndTime constraint’s value, then it is equal to workEndTime minus workStartTime and lunchDuration. Example : For a vehicle to work for 6 hours between 7PM and 7AM, set * optimumStartTime=True * dailyWorkTime="06:00:00" * workStartTime="07:00:00" * workEndTime="19:00:00" For a vehicle to work for 8 hour between 8PM and 5AM with a one-hour break at 12:30, set * workStartTime="08:00:00" * workEndTime="17:00:00" * lunchDuration="01:00:00" * lunchTime="12:30:00" Type : "hh:mm:ss", DateTime. Default: : "24:00:00". |
string |
workPenalty |
The cost of a resource working for an hour. Use this constraint to specify the resource wages when working for an hour. Type : float. Default: : 9. Example : If workPenalty = 10 (euros per hour) and daily work time is about 8 hours, the total daily work cost is 10 * 8 = 80 euros. |
number |
workStartTime |
The start time of the resource work time window. Use this constraint to specify the time at which the tour must start. This time can be adjusted using the optimumStartTime parameter. Type : "hh:mm:ss", DateTime. Default: : "00:00:00". |
string |
workingDays |
The resource’s work days. Use this constraint to specify the days a resource works in the planning period. This constraint is linked with the orders possible visit days constraints of Orders object elements and with the depot days of opening constraints of Depots object elements. Thus, customers and resources must have matching days for deliveries to be possible, and depots must be opened on resources working days to be used. A maximum of 64 days can be defined as work days. Working days can be written as integers (1,2???) or dates (14/05/2010, 15/05/2010, ???). If you are using dates, the oldest date in the workDays constraint defines day 1. Type : string values containing days separated with commas (like "1, 2, 5" or "14/05/2010, 15/05/2010, 18/05/2010" to specify day 1, day 2 and day 5) or intervals (like "1-10", "2=>5" or "14/05/2010=>24/05/2010") where 1 (or 14/05/2010) is the first day of the planning period. For day intervals, prefer the "=>" separator. Be careful, if the separator of date is - then "1-5" corresponds to May 1st of the current year. If you mix integer and date formats, beware that day 1 will all the same be defined by the oldest available date. Default: : "1". Example : You can define a single working day: Specify "1", "3" or "10" for the resource to work on day 1, day 3 or day 10 of the planning period. You can also define working periods. Specify "1-5" or "1=>5" or "14/05/2010=>18/05/2010" for the resource to work on a 5-days period (from day 1 to day 5 included). You can also mix single day and periods. Specify "1, 3=>5" for the resource to work on day 1 and from day 3 to 5 of the planning period. |
string |
Polymorphism : Composition
Name | Description | Schema |
---|---|---|
depots |
||
nbCapacities |
number |
|
nbExtraTravelPenalties |
number |
|
nbQuantities |
number |
|
nbTimeWindows |
number |
|
options |
||
orders |
||
resources |
Time window
Polymorphism : Composition
Name | Description | Schema |
---|---|---|
beginTime |
the minimum begin time Type : Time ("hh:mm" or "hh:mm:ss") |
string |
endTime |
the maximum end time Type : Time ("hh:mm" or "hh:mm:ss") |
string |
Details of a stop within a resource tour.
Polymorphism : Composition
Name | Description | Schema |
---|---|---|
additionalCost |
Additional cost Additional cost depends on additional cost configuration specified on resources and orders |
number |
dayId |
day of the tour |
string |
deliveryCost |
Total delivery cost of the tour Delivery cost depends on PenaltyPerVisit defined on resources and configuration specified in options (see countDepotsInDeliveryCost and countVisitCostOnceIfSameLocation) |
number |
plannedOrders |
Orders planned in this tour |
|
reloadNb |
ReloadNb Number of reloads during this tour |
number |
resourceCapacities |
List of resource capacities |
number |
resourceId |
Assigned resource identifier |
string |
totalCost |
Total cost Total cost = (delivery cost) + (additional cost) |
number |
travelDistance |
drive distance for this tour |
number |
travelDuration |
drive duration for this tour |
string |
usedCapacities |
List of used capacities Tour used capacities can exceed resource capacities if the tour contains one or several stops to a depot. |
number |
Polymorphism : Composition
Name | Description | Schema |
---|---|---|
distance |
The driven distance (in the solver’s measurement system unit) from which distance cost will be applied. Use this constraint when you need to specify a distance cost which can vary according to the covered distance. Up to 4 different distance costs can be specified. Each one must be related to the corresponding distance threshold, from which it will be applied |
number |
penalty |
The cost for a resource of driving for one distance unit. Use this constraint to specify the average resource taxes (gazoline, wear,???) when driving one distance unit. Type : float Default : 1.5 Example : if penalty = 0.5 (euro per distance unit) and the driven distance is about 100 unit (km or miles), the total distance cost is 0,5 * 100 = 50 euros. |
number |
Polymorphism : Composition
Name | Description | Schema |
---|---|---|
length |
Indicates the duration on which to apply the travel time modifier. Type : Time ("hh:mm" or "hh:mm:ss") or Integer (number of minutes). Default : 0 |
string |
offset |
Indicates the offset of the travel time modifier. Type : Time ("hh:mm" or "hh:mm:ss") or Integer (number of minutes). Default : 0 |
string |
value |
Indicates the value of the travel time modifier. When reaching a location situated in a large city, one may want to take into account driving difficulties, such as narrow streets and congestion. The travel time modifier enables to increase the travel times around a location. It is describes by three values. The value by which multiply the travel times around the location (tsDepotTravelTimeModifierValue), the portion of the travel time on which the modifier applies (length) an offset to add to any travel duration leaving or reaching the location (offSet). Example : * Set tsResource TravelTimeModifier Value to 1.5, tsResource TravelTime Modifier Length to 300 and tsResource TravelTimeModifier OffSet to 60 for Resource 1 * Set tsDepot TravelTimeModifier Value to 2, tsDepot TravelTimeModifier Length to 420 and tsDepot TravelTimeModifier OffSet to 0 for Depot 1 If the initial travel duration between Resource 1 and Depot 1 was 1000, one obtains a travel time 360 * 1.5 + 60 + 280 + 420 * 2 + 0 = 1660 Type : float Default : 1 |
number |
Unplanned order
Polymorphism : Composition
Name | Description | Schema |
---|---|---|
reason |
the reason why it what not planned |
string |
stopID |
The id of the stop. |
string |
Warning message (and associated error code) about possible Orders and Resources elements constraints misconfiguration.
The Solver object checks automatically data configuration (if not done yet) before the optimization begins. Whenever values are detected as incoherent or invalid, warnings are emitted in the Warnings property of the involved element. Depending the warning, constraints value can be replaced by their default value or not.
Polymorphism : Composition
Name | Description | Schema |
---|---|---|
constraint |
id of constraint causing the warning |
number |
constraintName |
string |
|
i18nMessageCode |
string |
|
id |
if of object causing the warning |
string |
message |
warning message |
string |
messageId |
number |
|
objectType |
type of object causing the warning |
string |
value |
string |
Polymorphism : Composition
Name | Description | Schema |
---|---|---|
id |
string |
|
language |
string |
|
orders |
Polymorphism : Composition
Name | Description | Schema |
---|---|---|
message |
string |
|
status |
string |
generic result of service
Polymorphism : Composition
Name | Description | Schema |
---|---|---|
depots |
List of depots |
|
message |
error message |
string |
status |
response status, OK or ERROR |
generic result of service
Polymorphism : Composition
Name | Description | Schema |
---|---|---|
lastKnownPosition |
List of positions |
|
message |
error message |
string |
operationalOrderAchievements |
List of orders |
|
status |
response status, OK or ERROR |
Polymorphism : Composition
Name | Description | Schema |
---|---|---|
address |
string |
|
addressComplement |
string |
|
city |
string |
|
country |
string |
|
geocodeAddressLine |
string |
|
geocodeCity |
string |
|
geocodePostalCode |
string |
|
geocodeType |
number |
|
postcode |
string |
|
region |
string |
|
score |
number |
Result of the optimize service
Polymorphism : Composition
Name | Description | Schema |
---|---|---|
message |
error message |
string |
status |
response status, OK or ERROR |
|
token |
the token string |
string |
validUntil |
The token validity end date |
string |
Operational planning export parameters
Polymorphism : Composition
Name | Description | Schema |
---|---|---|
dayNums |
number |
|
force |
if true, any existing operational planning will be replaced if false and if optimization period overlaps any existing operational planning, export will fail. |
boolean |
resourceMapping |
List of MobileResourceMapping defining relation between resource identifier in optimize request and real mobile resource identifier |
|
startDate |
real date corresponding to day 1 of optimize request data |
string |
taskId |
Task identifier. Must point to a completed optimization. |
string |
Polymorphism : Composition
Name | Description | Schema |
---|---|---|
accuracy |
GPS positioning accuracy (radius in meters) |
number |
batteryLevel |
Battery level of the device |
number |
date |
last position recording date |
string |
gpsStatus |
GPS status of the device |
|
id |
string |
|
lat |
Latitude |
number |
lon |
Longitude |
number |
privateLife |
Private life status in Mobile App. If true, it means that mobile App is currently in Private life mode, therefore this position is the last known position before the Private life switch. |
boolean |
Polymorphism : Composition
Name | Description | Schema |
---|---|---|
achievementComment |
Achievement comment |
string |
achievementEnd |
Achievement end date and time |
string |
achievementEndLat |
Achievement end latitude |
number |
achievementEndLon |
Achievement end longitude |
number |
achievementStart |
Achievement start date and time |
string |
achievementStartLat |
Achievement start latitude |
number |
achievementStartLon |
Achievement start longitude |
number |
apprauchSmsId |
string |
|
apprauchSmsStatus |
string |
|
data |
fulfillment form data |
object |
date |
Planning day |
string |
end |
Planned end date and time |
string |
feedbackSmsId |
string |
|
feedbackSmsStatus |
string |
|
geocode |
||
id |
string |
|
lastSynchroStatusChange |
Last change from mobile app |
string |
lat |
Latitude |
number |
lon |
Longitude |
number |
operationalResourceId |
Mobile resource identifier (mobile app login) |
string |
order |
Original order |
|
pictures |
List of picture relative urls. Url root for pictures is https://geoservices.geoconcept.com/ToursolverCloud/api/rest/otmobile/pictures/ |
string |
plannedOrder |
Planned order |
|
signaturePicture |
Signature, as a picture relative URL (a flavor of the reference signatureSvg) Is bound and synced from the signaturesSvg field. Is a relative URL, as also done for the pictures field (see its documentation for details). |
string |
signatureSvg |
Signature svg |
string |
simulationDayId |
day containing this order in the simulation used to fill the fulfillment planning |
string |
simulationId |
identifier of the simulation used to fill the fulfillment planning |
string |
start |
Planned start date and time |
string |
status |
fulfillment status |
|
synchroStatus |
Sync status |
|
timeWindowEnd |
string |
|
timeWindowSmsId |
string |
|
timeWindowSmsStatus |
string |
|
timeWindowStart |
string |
|
type |
Event type |
Type : enum (CANDIDATE, FIXED, ACCEPTED, REFUSED, STARTED, FINISHED, CANCELLED, PAUSED, RESUMED, UNKNOWN)
Type : enum (MISSION, RESTBREAK, LUNCHBREAK, WAITBREAK, RELOADBREAK, START, END, ENDBEFORENIGHT, STARTAFTERNIGHT, BRIEFING, DEBRIEFING, UNKNOWN)
The mobile resource mapping links the resource identifier used in optimized data and the mobile resource identifier used for operational planning export
Polymorphism : Composition
Name | Description | Schema |
---|---|---|
id |
resource identifier |
string |
operationalId |
Mobile identifier |
string |
Result of an optimization task.
Polymorphism : Composition
Name | Description | Schema |
---|---|---|
message |
error message |
string |
plannedOrders |
the planned stops |
|
simulationId |
Id of the simulation associated to this task |
string |
status |
response status, OK or ERROR |
|
taskId |
the id of the optimization task (usefull if result is automatically sent through a webhook). |
string |
unplannedOrders |
the orders which has not been planned because: <li>it was sent by an other mail service <li>it was not scheduled by any resource. |
|
warnings |
the list of warning messages (and associated error codes) about possible Orders and Resources elements constraints misconfiguration. |
Result of status request
Polymorphism : Composition
Name | Description | Schema |
---|---|---|
currentCo2 |
Remaining Kg CO2 of the current solution |
number |
currentCost |
Cost of the current solution |
number |
currentCourierCost |
Courier cost of the current solution |
number |
currentDeliveredQuantity |
Total quantity delivered of the current solution |
number |
currentDeliveryCost |
Delivery cost of the current solution |
number |
currentDriveCost |
Drive cost of the current solution |
number |
currentDriveDistance |
Drive distance of the current solution |
number |
currentDriveTime |
Drive time in seconds of the current solution |
number |
currentFixedCost |
Fixed cost of the current solution |
number |
currentLateTime |
Late time in seconds of the current solution |
number |
currentNightsCost |
Nights cost of the current solution |
number |
currentOpenTourNumber |
initial number of open tours (tours with at least one visit) |
number |
currentOverWorkCost |
Overwork cost of the current solution |
number |
currentOverWorkTime |
Over work time in seconds of the current solution |
number |
currentPickUpQuantity |
Total quantity picked-up of the current solution |
number |
currentPlannedVisits |
Number of planned visits of the current solution (new engine only) |
number |
currentRestTime |
Rest time in seconds of the current solution |
number |
currentUnplannedVisits |
Number of visits unplanned or delivered by a courier of the current solution |
number |
currentVisitsNb |
number |
|
currentWaitTime |
Wait time in seconds of the current solution |
number |
currentWorkCost |
Work cost of the current solution |
number |
currentWorkTime |
Work time in seconds of the current solution |
number |
initialCo2 |
Remaining Kg CO2 of the initial solution |
number |
initialCost |
Cost of the initial solution |
number |
initialCourierCost |
Courier cost of the initial solution |
number |
initialDeliveredQuantity |
Total quantity delivered of the initial solution |
number |
initialDeliveryCost |
Delivery cost of the initial solution |
number |
initialDriveCost |
Drive cost of the initial solution |
number |
initialDriveDistance |
Drive distance of the initial solution |
number |
initialDriveTime |
Drive time in seconds of the initial solution |
number |
initialFixedCost |
Fixed cost of the initial solution |
number |
initialLateTime |
Late time in seconds of the initial solution |
number |
initialNightsCost |
Nights cost of the initial solution |
number |
initialOpenTourNumber |
initial number of open tours (tours with at least one visit) |
number |
initialOverWorkCost |
Overwork cost of the initial solution |
number |
initialOverWorkTime |
Over work time in seconds of the initial solution |
number |
initialPickUpQuantity |
Total quantity picked-up of the initial solution |
number |
initialPlannedVisits |
Number of planned visits of the initial solution (new engine only) |
number |
initialRestTime |
Rest time in seconds of the initial solution |
number |
initialUnplannedVisits |
Number of visits unplanned or delivered by a courier of the initial solution |
number |
initialWaitTime |
Wait time in seconds of the initial solution |
number |
initialWorkCost |
Work cost of the initial solution |
number |
initialWorkTime |
Work time in seconds of the current solution |
number |
message |
error message |
string |
mileageChartRemainingTime |
Mileage and travel time matrix computing remaining time. This information may not be available depending on the geographical area. |
number |
optimizeStatus |
Current status of the optimization process |
|
simulationId |
Id of the simulation associated to this task |
string |
startTime |
Start time of the optimization |
string |
status |
response status, OK or ERROR |
|
subOptimAbortedNb |
Number of sub-optimizations in aborted state |
number |
subOptimErrorNb |
Number of sub-optimizations in error state |
number |
subOptimFinishedNb |
Number of sub-optimizations in finished state |
number |
subOptimNb |
Number of sub-optimizations created (after pre-sectorization) |
number |
subOptimRunningNb |
Number of sub-optimizations in running state |
number |
subOptimWaitingNb |
Number of sub-optimizations in waiting state |
number |
Result of status request
Polymorphism : Composition
Name | Description | Schema |
---|---|---|
firstStopAsked |
First stop demand stamp |
string |
message |
error message |
string |
status |
response status, OK or ERROR |
Result of an optimization task.
Polymorphism : Composition
Name | Description | Schema |
---|---|---|
message |
error message |
string |
status |
response status, OK or ERROR |
|
taskId |
the id of the optimization task (usefull if result is automatically sent through a webhook). |
string |
tours |
List of tours (one tour per resource per day) |
|
unplannedOrders |
the orders which has not been planned because: <li>it was sent by an other mail service <li>it was not scheduled by any resource. |
|
warnings |
the list of warning messages (and associated error codes) about possible Orders and Resources elements constraints misconfiguration. |
Optimization request
Polymorphism : Composition
Name | Description | Schema |
---|---|---|
beginDate |
This date will be used if you try to export the optimization result through TsCloud GUI. Format : YYYY-MM-DD Default : day+1. |
string |
countryCode |
Main country code used to route the optimization to the good optimization server farm. |
string |
depots |
list of depots (for reloading or starting tours) |
|
language |
Language to use for message localization |
string |
options |
the optimize task options |
|
orders |
list of orders (visits to do) |
|
organization |
In multi-user content, you generally create various organizations that allows to define who sees what. If you set the organization here, only users that can see this organization will see the result of this optimization in the UI. Note that if you specified a teamId instead of sending the resources in the optimization data, the organization will be guessed from the team. If no organization is set, all users will see the result. |
string |
resources |
collection of resources, the elements which will perform deliveries, pick-ups, commercial visit, etc. |
|
simulationName |
Simulation name Optional : generated automatically if not provided |
string |
userLogin |
In multi-user content, you can specify a user login you. The simulation will be owned by this user. By default, the owner of the simulation is the default user of the account. |
string |
Result of the optimize service
Polymorphism : Composition
Name | Description | Schema |
---|---|---|
message |
error message |
string |
status |
response status, OK or ERROR |
|
taskId |
the id of the optimization task that was launched |
string |
Type : enum (undefined, waiting, geocoding, mileageChartBuilding, running, aborted, terminated, error, sectorizationWaiting, sectorizationRunning, sectorizationFinished, sectorizationAborted)
generic result of service
Polymorphism : Composition
Name | Description | Schema |
---|---|---|
message |
error message |
string |
resources |
List of resources |
|
status |
response status, OK or ERROR |
generic result of service
Polymorphism : Composition
Name | Description | Schema |
---|---|---|
message |
error message |
string |
simulation |
||
status |
response status, OK or ERROR |
generic result of service
Polymorphism : Composition
Name | Description | Schema |
---|---|---|
message |
error message |
string |
status |
response status, OK or ERROR |
<p>Classe Java pour GPSStatus.
<p>Le fragment de sch??ma suivant indique le contenu attendu figurant dans cette classe. <p> <pre> <simpleType name="GPSStatus"> <enumeration value="0"/> <enumeration value="1"/> <enumeration value="2"/> </restriction> </simpleType> </pre>
Type : enum (0, 1, 2)