Tour Planning
Tour Planning API is designed to support complex route optimisation scenarios. It provides flexibility to create route plans using multiple configurations to select Vehicle Types, Fleet Capacity, Multiple Pick & Drop locations, and choosing delivery time window.
- Base URI : https://api.unl.global/{version}
Endpoints#
POST https://api.unl.global/v1/tourplanning
Required headers#
x-unl-project-id: Pass the unique Project Id also known as VPM Id under this parameter.
x-unl-api-key: Secure key to authorize the access to endpoints.
Request Parameters#
Body Parameters
fleet: fleet is an array object that specifies the vehicle type for serving jobs.
profile:profile is an object representing details of the vehicle. It captures the vehicle type, departureTime, and avoid properties. It is a required object for the fleet definition.type: represents transport mode of the vehicle type. It takes enum values of scooter, bicycle, pedestrian, car, and truck. This is a required property.departureTime: An optional parameter to specify departure time of the vehicle.avoid: It is optional parameter, used to set route avoidance options. It takes enum values of tollRoad, ferry, tunnel, dirtRoad, motorway.
cost: It defines vehicle costs per unit. It is a required object for fleet definition.fixed: An optional parameter to define fixed cost of using a vehicle. Default value is 0.distance: An Optional parameter representing cost per distance. Default value is 0.time: An Optional parameter representing cost per second. Default value is 0.
shifts: The shift parameter can be used to represent shift per vehicle type. The shift consists start, end and breaks properties.start: Start represents vehicle starting point, typically a depot. This is a required object and it consists of location and time propertieslocation: The object represents geospatial location in the form of either a geohash or 'latitude and longitude'. This is required objects.
time: represents start or departure time in the standard defined by RFC3339
end: An optional parameter to represent the end of the trip, typically a depot. It follows the object structure of 'start' parameter.breaks: It represents breaks as time windows for vehicle type during working hours. It is a required object that consists of times and duration.times: It represents a time array that shows multiple time windows. Its elements are date-time units as defined by RFC3339.duration: It represents the duration of the break in seconds.
capacity: It represents units of measure, e.g. volume, mass, size, etc. It takes a number array to specify units. It is also a required property for shift object definition.limits: It specifies constraints that are applied to vehicle type. It consists of maxDistance and shiftTime properties.maxDistance: It represents a maximum distance in meters per shift. It takes a number.shiftTime: It defines the maximum allowed working time of a vehicle type. In case a break is defined for this particular vehicle type, the duration of the break should be added to the shiftTime. For instance, if a vehicle type has a shift of 8 hours and a 30 minutes break, the total shiftTime should be defined as 8 hours 30 minutes.
amount: It represents the number of available vehicles. It takes a number.
jobs : It is an array object that lists all the available jobs. Currently, the upper limit of jobs is 250 for solving problems. It is a required array of objects for the request body.
pickups: It represents pickups between start and endpoints. It is a required object that consists of places and demand propertiesplaces: It is an array of objects containing location and duration properties. It is required.location: It is an object that represents geospatial location defined by either geohash or latitude and longitudeduration: It represents the duration of the pickup in seconds.
demand: It represents units of measure, e.g. volume, mass, size, etc. It is an array of numbers that specifies units
deliveries: It represents deliveries between start and endpoints. It is the object as same as pickups containing places and demand properties inside.priority: It specifies the priority of the job with 1 for high priority jobs and 2 for normal jobs. The default value is 2. It is an optional property for job object.
- Sample Request Body
Response Parameters#
overview: The object consists of overall cost, duration, length, and times of the trip.
cost: It represents the total cost for the tours.duration: It represents the total duration in seconds for the tours.length: It represents the total distance in meters for the tours.times: It represents the total time consumption during the various activities. It is an object containing driving, serving, waiting, and break.driving: It represents the total elapsed time during driving in seconds.serving: It represents the total elapsed time during serving in seconds.waiting: It represents the total elapsed time during waiting in seconds.break: It represents the total elapsed time during a break in seconds.
tours: The object contains vehicleId and stops array. It represents a solution to the optimization problem as per configuratons provided in the request body. All the stops are shown in a sequenced order inside the array.
vehicleId: It represents each fleet with a unique identifier. It is generated randomly by the system during the calculation. There is suffix information on vehicleId. It can be easily figured out which fleet is assigned to this job by checking the suffix. There is also an indicator showing the number which is the same order in the request body for each fleet.stops: It is an object array that contains stop objects inside. Each stop object consists of location, arrival, departure, load, and activities properties.location: It represents geospatial location defined by geohash string.departure: It represents the departure time of each stop point for the vehicle type. It is a date-time unit as defined by RFC3339.arrival: It represents the arrival time of each stop point for the vehicle type. It is a date-time unit as defined by RFC3339.load: It represents units of measure, e.g. volume, mass, size, etc. It is an array of numbers that specifies units.activities: It represents a list of activities to be done on stop. It is an object that consists of jobId, type, location, start and end properties.jobId: It represents each job with a unique identifier. It is generated randomly by the system during the calculation. There is suffix information on jobId. It can be easily figured out which job is assigned to which vehicle type by checking the suffix. There is also an indicator showing the number which is the same order in the request body for each job.type: It represents a type of activity. It takes an enum value such as departure, arrival, pickup, delivery, and break.location: It represents geospatial location defined by geohash string.start: It represents the start time of the job or activity on the stop point. It is a date-time unit as defined by RFC3339.end: It represents the finish time of the job or activity on the stop point. It is a date-time unit as defined by RFC3339.
overview: The object consists of cost, duration, length, and times between the source and its immediate destination locations.
cost: It represents the total cost for the tours.duration: It represents the total duration in seconds for the tours.length: It represents the total distance in meters for the tours.times: It represents the total time consumption during the various activities. It is an object containing driving, serving, waiting, and break.driving: It represents the total elapsed time during driving in seconds.serving: It represents the total elapsed time during serving in seconds.waiting: It represents the total elapsed time during waiting in seconds.break: It represents the total elapsed time during a break in seconds.
- Samples Response
API Response Code
200 : HTTP ok - Request was successfully processed
201 : HTTP created - Bulk job successfully created
401 : HTTP unauthorized - User does not have permission to carry out this action