Driv.in is a software that allows to optimize fleet routing. It assigns each order to an available vehicle, maximizing the global fleet usage. Then it defines an optimal delivery sequence that minimizes the total distance travelled while meeting the expected delivery time windows.The system is accessible from app.driv.in with a username and password, that are provided by our support team.
After reading this manual, the user will be able to:
SERVICE TIME It ́s the time, in minutes, that it takes to do a delivery.
TIME WINDOW It ́s the time range in which the client can receive a delivery.
ADDRESS It ́s the location for the delivery. It should have the street name and number, the district and the country (e.g., Presidente Errazuriz 4125, Las Condes, Chile). Additionally, you can have a service time and time window associated with a delivery.
DELIVERY ORDER These are items that the company has to delivery to its customers. They must have a delivery code, an address and units to be delivered (kg, m3 or other).
VEHICLES Are the available trucks that the company has to make the deliveries. They must contain a code and a capacity (kg, m3 or other).
GROUP OF VEHICLES Are a set of vehicles which may be used to make a planning scenario.
ROUTE PLAN It ́s a workday, where deliveries to customers are made from warehouse using the company vehicles. One scenario involves the definition of a warehouse, the fleet to be used, dispatch orders and other optional parameters.
1. SETTING FLEETS
To add vehicles, you can enter them manually page (1) or import an Excel file with the characteristics of the fleet (2). On the same page, you can find available a template to load the vehicles (3).
The mandatory fields are code, description and capacity of the vehicles. This last one is measured in “units” and can be kilograms, cubic meters, money, etc, the one that best represents what we are delivering.
These units must be the same used in the dispatch orders.
To create a group, you should select from the main menú vehicles/ vehicle group, put a name for the group and select vehicles belonging to this group. You can create multiple groups where they can share vehicles. The mandatory fields are code, description and capacity of the vehicles.
You can edit the vehicles at any momento, but you must consider that if you have used them in previous scenarios, then those results can be changed.
You could also edit the group of vehicles, affecting future scenarios.
2. SETTING ADDRESSES
If you have a list of customers with addresses, load them in the master addresses. However, every time you add a new client ́s address, it will automatically be saved in the master, avoiding to geo-referencing the addresses each time they are used.
Same as what is done in the settings of the vehicles in the master page, addresses can be added manually (1) or massively (2) for which a template is available in the form of address (3).
The mandatory fields are Street name and number, district and country. Additionally, it is recommended to have a customer code and / or location to avoid involuntary errors that can change the addresses. If the customer has a specific time service and / or a time window where they can receive the orders it is also recommended to set them in the master file, so they will be used every time you do an scenario with that client.
When massively addresses are loaded, it is possible that the system doesn ́t the exact coordinates of the customer's address. When that happens this address will be displayed in red and the user will have to edit the addresses and then confirm the exact location on the map. Addresses that cannot be georeferenced are not allowed to be in a scenario, so they must be taken out for the scenarios to be optimized.
You can modify or delete an address at any moment, but you must consider that if the address was used in a previous scenario, its result may be affected.
3. CREATE A ROUTE PLAN
To create a planning scenario, you have to press in the main menu "New route".
The first page consists of:
a.Warehouse: choose the warehouse from where all vehicles start the route.
b. Vehicles: Choose the number of vehicles and their capacity, in case you do not have the vehicles or fleets set up.
c. Options: You may have different conditions in a plan.
d. Working hours: you should select a work schedule in the which deliveries are made. It is possible that having defined time windows in the master address, they can be changed by working hours. For example, if a customer has a time windowf rom 8am to 11am and working hours it is from 9am to 7pm, the customer will see modified his time window from 9am to 11am. In addition to this, if a client has not defined a time window individually or in the master address, they could be dispatched at any time during the working hours.
e.ervice time: is the time that deliveries that have not been defined service time individually or in the master address, will take into account.
On the second page, you must load dispatch orders to the scenario.
Additionally, you can load other parameters such as time service or time window. This will be a priority over the ones defined in the master address and be used only in this scenario. In the case where an order does not come with these parameters and are not defined in the master address, the values are going to be by default the ones you put in the first page when building the scenario.
In case the order is not associated with a geo-referenced address or the system cannot find the exact coordinates of the address given, the order appears in red and the scenario cannot be optimized until address is edited and confirmed the exact location of the address.
Having done the above, it must be saved and then optimize in order to obtain an optimal planning.
4. STATUS, VISUALIZATION AND EXPORT OF RESULTS PLANNING
By creating a scenario, it can have several diferent status:.
Ready to optimize: Eeverything is ok and it is possible to optimize given the parameters given.
Incomplete: it means that there are some addresses that do not have the exact Coordinates, so it is not possible to optimize. To fix this, you must edit the scenario and edit or delete those addresses that areshowed in red.
Repairable: It means that there are some orders that are not possible To satisfy the conditions of the scenario. For example, an order that exceeds the maximum capacity of a vehicle or an address that has a time window that cannot be delivered given the working hours. To continue, press repair and the system exclude the solution that are not able to deliver and continues with the optimization.
Not feasible: There are some conditions where the system cannot find an optimal solution. Among the main causes you can find:
Optimized: It means that an optimal solution was found. If the characteristics of the scenario are not possible to satisfy all restrictions, the system displays additional vehicles in those orders that cannot be incorporated into the scenario.
When the setting is "optimized", it is possible to visualize the Planning output. You can see the trucks used,kilometers traveled, estimated time of arrival of the vehicles to each point of delivery and other indicators of the scenarios.
The results can be exported to an Excel spreadsheet, or to a PDF if it wants to be printed for the drivers.
The system has a remote support by chatting enabled at the bottom right hand side, where any enquiries can be asked and are answered as soon as possible.
In case you cannot access the page, require additional training or need to train new users, you can send an email to contacto@driv.in and you will be contacted asap.
Drivin is a software that enables companies that deliver to many clients in a day, to plan their routes optimally.
To start using these APIs, we recommend you to read the user manual first, so you have a better understanding of the conceps used.
This set of APIs allows you to do the following:
1. Create scenarios
2. Check the status of the scenarios
3. Optimize the scenarios
4. Obtain results of the scenarios
5. Edit some characteristics of the fleet
To have access to the actions described above you require the following headers: X-API-Key y Content-Type: application/json. To obtain an Api key, you must contact ops@driv.in
When using Apis, the normal process should be:
1. Generate a scenario (.../scenarios)
2. Check the status until the answer is "Ready" (.../status)
3. Send to optimize (.../optimize)
4. Check the status until the answer is "Optimized" (.../status)
5. Obtain results (.../results)
Below you will find a list of all the actions, parameters and responses you can obtain.
POST
https://app.driv.in/api/external/v1/scenarios
Through this action you can create scenarios. The parameter type is "body". In the answer you obtain a token that will allow you to identify the scenario
Campos | Tipo | Descripción |
---|---|---|
description | string | Name of the scenario |
date | string | Date of the scenario in format "yyyy-mm-dd" |
start | string | Start time of the shift "hh:mm" |
end | string | End time of the shift "hh:mm" |
return_trip | boolean optional | Specifies if the vehicles must return to the deposit after finishing the deliveries, default=TRUE |
multiple_trips | booleanoptional | Allows the vehicles to do more than one trip in the day, default=FALSE |
reload_time | integeroptional |
Time in minutes that the vehicles takes to load at the deposit when the vehicle is allowed to do more than one trip. If multiple_trips=TRUE, this is a required field. |
deposit | JSON[] | Place where the routes start |
code | stringoptional | Code of the deposit |
description | stringoptional | Description of the deposit |
address | string | Address of the deposit |
city | string | City of the deposit |
country | string | Country of the deposit |
lat | number | Latitud in degrees |
lng | number | Longitud in degrees |
fleet | JSON[] | set that describes the vehicles to be used in the scenario |
code | string | Code that identifies the vehicle |
description | stringoptional | More information regarding the vehicle |
capacity_units | integer | Capacity of the vehicle in units |
capacity_units_2 | integeroptional | Secondary capacity of the vehicle in units |
tags | stringoptional | Skills that owns the vehicle. You can define multiple tags separated by commas. |
clients | JSON[] | Set that defines the orders to be delivered to a client |
code | stringoptional | Code that identifies the address of a client |
address | string | Address |
reference | stringoptional | Reference |
city | string | City |
country | string | Country |
lat | numberoptional | Latitud in degrees |
lng | numberoptional | Longitud in degrees |
service_time | integer | Time in minutes it takes to deliver to the address |
timewindow | JSON[]optional | |
start | string | Start time that it is allowed to deliver to the address "hh:mm" |
end | string | End time that it is allowed to deliver to the address "hh:mm" |
tags | stringoptional | Skills that the vehicle serving the client must have. |
orders | JSON[] | |
code | string | Code that identifies the order |
description_code | stringoptional |
Code of a product of the order (SKU) |
description | stringoptional | Description of the product in the order |
units | number | Amount of units in the order |
units_2 | numberoptional | Amount of secondary units in the order |
{
"description": "Supermarket" 30/09/2015",
"date": "2015-09-30",
"start": "07:00",
"end": "18:00",
"return_trip": TRUE,
"multiple_trips": FALSE,
"reload_time": 0,
"deposit": {
"code": "D1",
"description": "Bodega Principal Stgo",
"address": "Presidente Errázuriz 4125",
"city": "Las Condes",
"country": "Chile",
"lat": -33.4199,
"lng": -70.5861,
},
"fleet": [
{
"code": "BHGF78",
"description": "Vehicle 1",
"capacity_units": 5000,
"capacity_units_2: 23,
"tags": "Small, Frozen"
}
],
"clients": [
{
"code": "A103",
"address": "José Pedro Alessandri 1166",
"reference": "Jumbo Ñuñoa",
"city": "Ñuñoa",
"country": "Chile",
"lat": -33.464095200,
"lng": -70.598207700,
"service_time": 90,
"time_window": {
"start": "07:00",
"end": "10:00"
},
"tags": "Small",
"orders": [
{
"code": "567789",
"description_code": "9786",
"description": "Yogurt Soprole",
"units": 234.5,
"units_2": 2
}
]
}
]
}
Campos | Tipo | Descripción |
---|---|---|
status | string | OK / Error |
response | JSON[] | |
scenario_token | string | Token that identifies the scenario for future actions (only if status = OK) |
description | string | Error message (only if status= Error) |
{
"status": "OK",
"response": {
"scenario_token": "5a696642-5363-4c6a-89fb-bafa22a4e92e"
}
}
GET
https://app.driv.in/api/external/v1/scenarios/{scenarioToken}/status
Through this action you can review the status of an scenario. The parameter type is "path".
Campos | Tipo | Descripción |
---|---|---|
status | string | OK / Error |
response | JSON[] | |
status | string | The different status of the scenarios are the following:
|
percentage | integer | It represents the percentage of progress when the status is "Optimizing" |
description | string |
Contains a message, in case there is an error in the scenario |
{
"status": "OK",
"response": {
"status": "Optimizing",
"percentage": 35,
}
}
POST
https://app.driv.in/api/external/v1/scenarios/{scenarioToken}/optimize
Through this action you can optimize the scenario that corresponds to ScenarioToken. You will only be able optimize the scenarios with status: "Ready". The parameter type is "path".
Campos | Tipo | Descripción |
---|---|---|
status | string | OK/ Error |
response | JSON[] | |
scenario_token | string |
The token of the scenario is returned (only if status = OK) |
description | string | Error message (only if status= Error) |
{
"status": "OK",
"response": {
"scenario_token": "5a696642-5363-4c6a-89fb-bafa22a4e92e"
}
}
POST
https://app.driv.in/api/external/v1/scenarios/{scenarioToken}/repair
Through this action you can repair the scenario that corresponds to ScenarioToken. The only scenarios that can be repaired are the ones with the status: "Repairable". The parameter type is "path".
Campos | Tipo | Descripción |
---|---|---|
status | string | OK / Error |
response | JSON[] | |
scenario_token | string |
The token of the scenario is returned (only if status = OK) |
description | string | Error message (only if status= Error) |
{
"status": "OK",
"response": {
"scenario_token": "5a696642-5363-4c6a-89fb-bafa22a4e92e"
}
}
GET
https://app.driv.in/api/external/v1/scenarios/{scenarioToken}/results
Through this action you can obtain the results of the optimization of a scenario. To obtain the results, the status of the scenario must be "Optimized", "Modified" o "Approved". The parameter type is "path". All the orders that were not assigned or are unfeasible are grouped in virtual vehicles (fleet field is null).
Response Class (Status 200)
Campos | Tipo | Descripción |
---|---|---|
status | string | OK / Error |
response | JSON[] |
If status=OK, contains a JSON describing a group of vehicles and the routes associated to them. If not, it contains a field "description" |
fleet | string | Code that identifies the vehicle |
orders | JSON[] | Set of orders associated to a vehicle |
position | integer | Place where the order must be delivered |
order | JSON[] | Information about the order |
code | string | Code associated to the order |
description_code | string optional | Code of a product of the order (SKU) |
description | stringoptional | Description of the product in the order |
units | integeroptional | Units of the SKU |
client | JSON[] | Client information associate to the order |
code | stringoptional | Code associated to the address |
address | string | Address of the client |
reference | stringoptional | Reference |
city | string | City |
country | string | Country |
lat | number | Latitud in degrees |
lng | number | Longitud in degrees |
service_time | integer | Time in minutes is takes to deliver to the address |
time_window | JSON[]optional | |
start | string | Start time that it is allowed to deliver to the address "hh:mm" |
end | string | End time that it is allowed to deliver to the address "hh:mm" |
eta | string | Estimated time of arrival to the address "hh:mm" |
description | string | Error message (only if status= Error) |
{
"status": "OK",
"response": [
{
"fleet": "BHGF78",
"orders": [
{
"position": 1,
"order": {
"code": "567789",
"description_code": "9786",
"description": "Yogurt Soprole",
"units": 234.5
},
"client": {
"code": "A103",
"address": "José Pedro Alessandri 1166",
"reference": "Jumbo Ñuñoa",
"city": "Ñuñoa",
"country": "Chile",
"lat": -33.464095200,
"lng": -70.598207700,
"service_time": 90,
"time_window": {
"start": "07:00",
"end": "10:00"
}
},
"eta": "08:14"
}
]
}
]
}
GET
https://app.driv.in/api/external/v1/scenarios/{scenarioToken}/grouped_results
Through this action you can obtain the results of the optimization of a scenario with the orders grouped by clients.
To obtain the results, the status of the scenario must be "Optimized", "Modified" or "Approved". The parameter type is "path". The answer may contain three stages:
Campos | Tipo | Descripción | |
---|---|---|---|
status | string | OK / Error | |
response | JSON[] | If status is OK, it may contain three stages (assigned, unassigned, infeasible) each one of them with a group of vehicles, clients and orders. If not, it contains the field "description" | |
assigned | JSON[] | Set of vehicles assigned | |
fleet | string | Code that identifies the vehicle | |
results | JSON[] | Set of clients with their eta, location and orders. | |
eta | string | Time estimated of arrival "hh:mm" | |
position | integer | Location to deliver the order | |
client | Information of the client, associated to the order | ||
code | stringoptional | Code associated to the address | |
address | string | Address of the client | |
reference | stringoptional | Reference | |
city | string | City | |
country | string | Country | |
lat | number | Latitud in degrees | |
lng | number | Longitud in degrees | |
service_time | integer | Time in minutes it takes to deliver to the address | |
time_window | JSON[]optional | ||
start | string | Start time that it is allowed to deliver to that address "hh:mm" | |
end | string | End time that it is allowed to deliver to that address "hh:mm" | |
orders | JSON[] | Set of orders associated to the client | |
code | string | Code associated to the order | |
description_code | string optional | Code of a product of the order (SKU) | |
description | stringoptional | Description of the product of the order | |
units | integeroptional | Units of SKU | |
unassigned | JSON[] | Set of clients without assignated vehicles | |
fleet | string | For this case all the values are null | |
results | JSON[] | Description of the client and its orders | |
client | Information of the client associated to the order | ||
code | stringoptional | Code associated to the address | |
address | string | Address of a client | |
reference | stringoptional | Reference | |
city | string | State (comuna) | |
country | string | Country | |
lat | number | Latitud in degress | |
lng | number | Longitud in degrees | |
service_time | integer | Time in minutes is takes to deliver to that address | |
time_window | JSON[]optional | ||
start | string | Start time that it is allowed to deliver to the address "hh:mm" | |
end | string | End time that it is allowed to deliver to the address "hh:mm" | |
orders | JSON[] | Set of orders associated to the clients | |
code | string | Code associated to the order | |
description_code | string optional | Code of a product assossiated to the order (SKU) | |
description | stringoptional | Description of the product of the order | |
units | integeroptional | Units of the SKU | |
infeasible | JSON[] | Set of clients with infeasible orders | |
fleet | string | In this case the value is null | |
results | JSON[] | Description of a client and its order | |
client | Information of the client associated to the order | ||
code | stringoptional | Code associated to the address | |
address | string | Address of a client | |
reference | stringoptional | Reference | |
city | string | State (comuna) | |
country | string | Country | |
lat | number | Latitud in degrees | |
lng | number | Longitud in degrees | |
service_time | integer |
|
|
time_window | JSON[]optional | ||
start | string | Start time that it is allowed to deliver to the address "hh:mm" | |
end | string | End time that it is allowed to deliver to the address "hh:mm" | |
orders | JSON[] | Set of orders associated to the client | |
code | string | Code associated to the order | |
description_code | string optional | Code of the product of the order (SKU) | |
description | stringoptional | Description of the product of the order | |
units | integeroptional | Units of SKU |
{
"status": "OK",
"response": {
"assigned": [
{
"fleet": "ABCD34",
"results": [
{
"eta": "06:54",
"position": 0,
"client": {
"code": "ADD36",
"address": "VARGAS TORRES 56",
"reference": "Oficina Empresas ABC",
"city": "Santiago",
"country": "Chile",
"lat": -33.407879600,
"lng": -70.555796000,
"service_time": 30,
"time_window": {
"start": "06:30",
"end": "17:30"
}
},
"orders": [
{
"code": "ORD7105",
"description_code": "9786",
"description": "Yogurt Soprole",
"units": 500
}
]
}
]
}
],
"unassigned": [
{
"fleet": null,
"results": [
{
"client": {
"code": "ADD98",
"address": "PRESIDENTE RIESCO 5711",
"reference": "Oficina Central Big",
"city": "Las Condes",
"country": "Chile",
"lat": -33.407879600,
"lng": -70.555796000,
"service_time": 30,
"time_window": {
"start": "06:30",
"end": "17:30"
}
},
"orders": [
{
"code": "ORD098",
"description_code": "9745",
"description": "Carrots",
"units": 1500
}
]
}
]
}
],
"infeasible": [
{
"fleet": null,
"results": [
{
"client": {
"code": "gm001",
"address": "SEGUNDA CONSTITUYENTE 78",
"reference": "CD Smart",
"city": "San Bernardo",
"country": "Chile",
"lat": -33.407879600,
"lng": -70.555796000,
"service_time": 30,
"time_window": {
"start": "06:30",
"end": "17:30"
}
},
"orders": [
{
"code": "ORD6782",
"description_code": "9213",
"description": "Smartphone",
"units": 4500
}
]
}
]
}
]
}
}
PATCH
https://app.driv.in/api/external/v1/scenarios/{scenarioToken}/routes
Through this action you can change a vehicle that was assigned to a route. The parameters type are "path" (scenarioToken) and "body".
Campos | Tipo | Descripción |
---|---|---|
RouteEdit | ARRAY[] |
Vehicle changes array |
target_fleet | JSON[] | Vehicle you wish to replace |
code | string | Code that identifies the vehicle |
description | string | Aditional information related to the vehicle |
capacity_units | integer | Capacity of the vehicle in units |
replacement_fleet | JSON[] | Vehicle you would like to use to replace the one before |
code | string | Code that identifies the vehicle |
description | string | Aditional information related to the vehicle |
capacity_units | integer | Capacity of the vehicle in units |
[
{
"target_fleet": {
"code": "BHGF78",
"description": "vehicle 1",
"capacity_units": 5000
},
"replacement_fleet": {
"code": "JHYI66",
"description": "vehicle 2",
"capacity_units": 6000
}
}
]
Campos | Tipo | Descripción |
---|---|---|
status | string | OK / Error |
response | JSON[] | |
scenario_token | string | Token that identifies the scenario for future actions (only if status =OK) |
description | string | Error message (only if status= Error) |
{
"status": "OK",
"response": {
"scenario_token": "5a696642-5363-4c6a-89fb-bafa22a4e92e"
}
}
DELETE
https://app.driv.in/api/external/v1/scenarios/{scenarioToken}/delete
Through this action you can delete a scenario. Parameter type is "path".
Campos | Tipo | Descripción |
---|---|---|
status | string | OK / Error |
response | JSON[] | |
description | string |
Message confirming you want to delete the scenario if status = Error |
{
"status": "OK",
"response": {
"description": "Scenario deleted"
}
}
GET
https://app.driv.in/api/external/v1/scenarios/{scenarioToken}/infeasibles
Through this action you can obtain all the orders that are unfeasible of a scenario. The parameter type is: "path"
Campos | Tipo | Descripción |
---|---|---|
status | string | OK / Error |
response | JSON[] |
If status= OK, it contains a set of unfeasible orders associated to a scenario. If not, it contains a field "description" |
order | JSON[] | Set that contains information of the order |
code | string | Code associated to the order |
description_code | string optional | Code of a product in the order (SKU) |
description | stringoptional | Description of the product of the order |
units | integeroptional | Units of the SKU |
client | JSON[] | Information of the client associated to an order |
code | stringoptional | Code associated to an address |
address | string | Address of a client |
reference | stringoptional | Reference |
city | string | State (Comuna) |
country | string | Country |
lat | number | Latitud in degrees |
lng | number | Longitud in degrees |
service_time | integer | Time in minutes it takes to deliver to the address |
time_window | JSON[]optional | |
start | string | Start time that it is allowed to deliver to the address "hh:mm" |
end | string | End time that it is allowed to deliver to the address "hh:mm" |
description | string | Error message (only if status = Error) |
{
"status": "OK",
"response": [
{
"order": {
"code": "50034721653",
"description_code": "1238228",
"description": "Chicken type A",
"units": 4500
},
"client": {
"code": "CO003",
"address": "ADD354",
"reference": "Supermarket Express"
"city": "Santiago",
"country": "Chile",
"lat": -33.419898987,
"lng": -70.586502075,
"service_time": 30,
"time_window": {
"start": "06:30",
"end": "17:30"
}
}
}
]
}