Planning API

Overview

The Planning API is a powerful N to N optimization service with many vehicle types like cars, trucks and that takes various constraints in consideration.


  • Use cases

    The Planning API can be used to solve multiple vehicle routing problems (VRP) and traveling salesman problems (TSP), considering business specific constraints such as time windows, multiple depots, multiple capacity dimensions, driver skills etc. defined by the user. It is applicable to solving both small and large scale problems.

  • First steps

    Before you start developing with the Planning API, review the authentication requirements (you need an API key) and the API usage limits.

Introduction

The Planning API works in 3 steps

  1. Post your logistic problem;
  2. Check the processing steps and status of the problem until a solution be available which could be through getting the status or a callback;
  3. Get the solution for your problem.

Posting a problem

To solve a logistic problem optimizing the operations and finding the best execution order, you need to send the problem to be solved by our services through the POST/problems method.

Parameters

Certain parameters are required while others are optional. The list of parameters and their possible values are enumerated below.

Mandatory Parameters

optimizationProfile

Indicates the default data that should be considered to optimize the route(s). The optimizationProfile parameter supports a profile id that should be previously defined during the API configuration with Maplink’s onboarding team. The default profiles for big problems: BRAZIL37, CHILE37, ARGENTINA37, COLOMBIA37, MEXICO37. The default profiles for small problems: BRAZIL46, CHILE46, ARGENTINA46, COLOMBIA46, MEXICO46

tripsProfile

Indicates the default data that should be considered to calculate the distance matrix between depots and sites. The tripsProfile parameter supports a profile id that should be previously defined during the API configuration with Maplink’s onboarding team. The default profiles are: MEXICO, COLOMBIA, CHILE, BRAZIL, ARGENTINA, EGYPT, EUROPE, FRANCE, SAUDIARABIA.

startDate

Indicates the specific date and time when route problem should be executed.

legislationProfile

Indicates that the optimization should take the drivers legislation into account.

name Profile name. Used for referencing and identification on result. It must be unique.
maxContinuousDrivingTime Indicates the maximum continuous driving time without pause, in seconds.
maxDrivingTimeBetweenTwoRests Indicates the maximum continuous driving time without rest, in seconds.
drivingPauseDuration Indicates the driving pause duration, in seconds.
drivingPauseDurationCuts Indicates if the driving pause duration can/should be splitted, and the duration of which cut, in seconds.
drivingRestDuration Indicates the driving rest duration, in seconds.
drivingRestDurationCuts Indicates if the driving rest duration can/should be splitted, and the duration of which cut, in seconds.
maxContinuousWorkingTime Indicates the maximum continuous working time without pause, in seconds.
maxWorkingTimeBetweenTwoRests Indicates the maximum continuous working time without rest, in seconds.
workingPauseDuration Indicates the working pause duration, in seconds.
workingPauseDurationCuts Indicates if the working pause duration can/should be splitted, and the duration of which cut, in seconds.
workingRestDuration Indicates the working rest duration, in seconds.
workingRestDurationCuts Indicates if the working rest duration can/should be splitted, and the duration of which cut, in seconds.
maxWaitingTime Indicates the maximum time waiting at the site to execute an operation.
waitingIsWorking Indicates if the time waiting at the side is considered as working time and supports the following arguments: TRUE, FALSE
LogisticConstraint

Indicates the constraints that should be taking into account for each depot or site that will be in the optimization.The LogisticConstraint parameter has the following fields:

name Constraint name. Used for referencing and identification on result. It must be unique.
siteLoadingFixedTime Indicates a fixed loading time in seconds.
siteUnloadingFixedTime Indicates a fixed unloading time in seconds.
loadingPositionInRoute Indicates the operation position in the route if the operation type is COLLECTION.
unloadingPositionInRoute Indicates the operation position in the route if the operation type is DELIVERY.
loadingPositionInTimeWindow Indicates the operation position in the time window if the operation type is COLLECTION.
unloadingPositionInTimeWindow Indicates the operation position in the time window if the operation type is DELIVERY.
loadingMaxSize Indicates the max vehicle size that a site supports if the operation type is COLLECTION.
unloadingMaxSize Indicates the max vehicle size that a site supports if the operation type is DELIVERY.
Product

Indicates the products that will be collected or delivered in each operation. The Product parameter has the following fields:

name Product name. Used for referencing and identification on result. It must be unique.
type Type of the product. Can be used for separation purposes.
sites

Indicates the client sites(s) that should be considered in the optimization. The sites parameter has the following fields:

name Site name. Used for referencing and identification on result. It must be unique.
coordinates Indicates the latitude and longitude point where the site is located.
logisticConstraints Reference to the Logistic constraint name, previously defined in the LogisticConstraint parameter.
depots

Indicates the depot(s) that should be considered in the optimization. The depots parameter has the following fields:

name Depot name. Used for referencing and identification on result. It must be unique.
coordinates Indicates the latitude and longitude point where the depot is located.
logisticConstraints Reference to the Logistic constraint name, previously defined in the LogisticConstraint parameter.
vehicleTypes

Indicates the types of vehicle that should be considered in the optimization. The vehicleTypes parameter has the following fields:

name Vehicle type name. Used for referencing and identification on result. It must be unique.
maxVolume Indicates the maximum volume in cubic meters.
maxWeight Indicates the maximum weight in tons.
size Indicates the size of the vehicle type.
vehicles

Indicates the vehicle that should be considered in the optimization. The vehicles parameter has the following fields:

name Vehicle name. Used for referencing and identification on result. It must be unique.
vehicleType Reference to the vehicle type name, previously defined in the vehicleTypes parameter.
legislationProfile Reference to the legislation profile name, previously defined in the legislationProfiles parameter.
availablePeriods Indicates the period that the vehicle is available.
availablePeriods

Indicates the time window that a vehicle is available. The availablePeriods parameter has the following fields:

departureSite Indicates the site from where the vehicle should depart.
arrivalSite Indicates the site where the vehicle should arrive by the end of a route.
timeWindow Indicates the starting and ending time of the vehicle availability.
maxRoutesNumber Indicates the maximum number of routes that the vehicle can execute during the available period.
operations

Indicates the operations of collect or delivery that should be considered in the optimization. The operations parameter has the following fields:

id Used for identification on result. It must be unique.
priority Indicates the operation priority compared to the others operations. Higher values mean higher priority.
weight Indicates the product weight in kilograms.
volume Indicates the product volume in cubic meters.
product Indicates the product that must be used in the operation. Reference to the product name, previously defined in the products parameter.
type Indicates if the operation is a collection or a delivery and supports the following arguments: COLLECTION, DELIVERY,
depotSite Indicates the depot that must be used in the operation. Reference to the depot name, previously defined in the depots parameter.
customerSite Indicates the site that must be used in the operation. Reference to the site name, previously defined in the sites parameter.
customerTimeWindows Indicates the customer time window in which the operation may take place.
customerHandlingDuration Indicates the time spent in the customer in seconds.
depotHandlingDuration Indicates the time spent in the depot in seconds.
preAllocatedVehicleName Indicates a predefined vehicle that should do the operation. Reference to the vehicle name, previously defined in the vehicles parameter.

Optional Parameters

callback

Allow to register an URL to receive a callback with the problem solving status.

password Access key to client’s system if it’s necessary.
url URL that will receive the problem solving status.
user User access to client’s system if it’s necessary.

Note: If you opt for using the ‘callback’ parameter in the POST/problems, check the GET/events responde description to know the parameters you will receive in return.

Response Parameters

The list of parameters and their possible values are enumerated below.

id

The id parameter is the identification of the problem that should be used to get the problem solving status and the problem solution.

Getting a problem

Request Parameters

Certain parameters are required while others are optional. The list of parameters and their possible values are enumerated below.

Mandatory Parameters

id

The id parameter is the identification of the problem that you get as response of posting a problem.

Response Parameters

Consult the Posting Problem Request Parameters.

Getting feedback

To follow the process of finding a solution for the problem, you should check the processing status through GET/jobs method.

Request Parameters

Certain parameters are required while others are optional. The list of parameters and their possible values are enumerated below.

Mandatory Parameters

jobId

The jobId parameter is the identification of the problem that you get as response of posting a problem.

Response Parameters

The list of parameters and their possible values are enumerated below.

job

Indicates the main information about the process to solve the problem

error Indicates the last error occurred during the processing.
id Indicates the processing ID.
percent The current percentage of the processing done.
status Indicates the current status of the processing.
step Indicate the current step inside the status.
warning Indicate a warning of the processing.

Feedback Status

For each step during the problem solving a different status is presented in the GET/jobs response.

ENQUEUED Indicates that the problem is ready to be processed.
PROCESSING Indicates that the problem solution is being calculates.
SOLVED Indicates that the solution is already available to be goten.
ERROR Indicates that an error occurred and it was not possible to calculate the solution.

Getting Events

To follow the process of finding a solution for the problem, you can check the events which are occurring during the processing through GET/events method.

Request Parameters

Certain parameters are required while others are optional. The list of parameters and their possible values are enumerated below.

Mandatory Parameters

jobId

The jobId parameter is the identification of the problem that you get as response of posting a problem.

Response Parameters

The list of parameters and their possible values are enumerated below.

job

Indicates the main information about the process to solve the problem.

description Indicates a description or value related to the event occurred during the processing.
jobid Indicates the processing ID.
type Indicates the event type that supports the following arguments:
STATUS_CHANGE,
ERROR,
STEP_CHANGE,
PERCENT_CHANGE,
WARNING

Getting a Solution

As soon as you have a SOLVED status from the GET/jobs method, you can get the problem solution through GET/solutions method.

Request Parameters

Certain parameters are required while others are optional. The list of parameters and their possible values are enumerated below.

Mandatory Parameters

id

The id parameter is the identification of the problem that you get as response of posting a problem.

Response Parameters

The list of parameters and their possible values are enumerated below.

solution

Indicates the consolidated information about the solution. The solution parameter has the following fields:

id Indicates the problem ID regarding this solution.
clientId Indicates the client ID who posted the problem regarding this solution.
createdAt Indicates the time and date when the solution was created.
indicators Indicates the summary of the calculation. See the detail in the Indicators parameter description.
rejectedOperations List of operations that wasn't possible to include in a route.
vehicleRoutes Indicates the vehicle that was designated to a route. See the detail in the vehicleRoute parameter description.
indicators

Indicates the summary of the calculation. The indicators parameter has the following fields:

averageOccupancyRateVolume Indicates the solution average volume occupancy rate, in cubic meters.
averageOccupancyRateWeight Indicates the solution average weight occupancy rate in kilograms.
dayWorkingTotalTime Indicates the solution total working time during the day.
nightWorkingTotalTime Indicates the solution total working time during the night.
rejectOperationsNumber Indicates the quantity of Operations that were rejected in the solution.
routesNumber Indicates the quantity of Routes that were created in the solution.
timeWindowNumber Indicates the quantity of Time Windows that were used in the solution.
totalCollectingTime Indicates the total time destined to execute Collecting Operations.
totalDeliveringTime Indicates the total time destined to execute Delivering Operations.
totalDistance Indicates the total distance.
totalDrivingTime Indicates the total driving time.
totalLoadingTime Indicates the total loading time.
totalRestTime Indicates the total driver’s rest time.
totalServiceTime Indicates the total time the drivers will be in service.
totalUnloadingTime Indicates the total unloading time.
totalWaitingTime Indicates the total waiting time.
totalWorkingTime Indicates the total working time.
vehicleRoute

Indicates the route(s) and vehicle that should be used to execute the solution. The vehicleRoute parameter has the following fields:

routes Indicates the routes created to solve the problem. Check the detail in the route parameter description.
vehicle Indicates vehicles that will be used to execute the routes.
routes

Indicates the list of activities that should be done to execute the route. The routes parameter has the following fields:

activities Indicates the list of activities that contain steps to be followed in a route. Check the detail in the ‘activities” parameter description.
activities

Indicates what should be done in each step of the route. The activities parameter has the following fields:

activity Indicates the name of the activity that supports the following arguments:
LOADING,
DRIVING,
DELIVERY,
ROUTE_START,
ROUTE_END
arrivalSite Indicates the arrival site where the activity will end if type = driving.
departureSite Indicates the departure site where the activity will start if with type = driving.
distance Indicates the distance between the departure site and the arrival site.
fixedTimeSite Indicates the total duration of an activity with type different from driving.
nominalDuration Indicates the total duration of an activity with type = driving.
operations Indicates the operations to be executed in the activity.
site Indicates the site where the operation will be executed.
timeWindow Indicates the time window when the activity will take place. Check the detail in the timeWindow parameter description.
type Indicates the type of activity that supports the following arguments:
SITE,
DRIVING
volume Indicates the total volume of the activity.
weight Indicates the total weight of the activity.
timeWindow

Indicates the date and time when the activity will take place. The timeWindow parameter has the following fields:

end Indicates the date and time when the activity will end.
start Indicates the date and time when the activity will start.
Maplink Platform

Contact us