DOCS

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:

  1. Create, edit and delete the fleet to be used.
  2. Create, edit and delete addresses from the customer master base.
  3. Create a scenario.
  4. Visualize and export the results obtained.

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


002


If you have a fleet with different capacities, it is necessary to make a configuration with the main characteristics of the fleet. Then you must create a group of vehicles.


004

 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.

005  

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

007

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:

008

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.

  • Back to the warehouse: Indicates whether the vehicles must return back to the warehouse after making all the deliveries.
  • Optimal allocation: Corresponds when the system can determine which vehicles make the deliveries. Otherwise, when all the orders are loaded, a vehicle must be assigned to each order in the Excel spreadsheet.
  • Multiple Trips: It indicates whether the vehicles are enabled to make more than one trip. If so, you must define how long you take to reload the vehicle. (Its the time that it takes since they arrive to the warehouse and leave again to start a another route).

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.

009

Orders can be added manually (1) or massively (2) for which it has a downloadable template (3) format for loading orders. Required fields for the order are: 
  • Delivery code
  • Address, district and country code
  • Units (must be consistent with the definition of units used when the vehicles capacity was established)

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:

  • Fleet capacity < Quantity transported (Note: If the option of multiple trips is activated, is not possible to detect a priori, if there is infeasibility)
  • Sum of Times Service> Working Hours x No.vehicles
  • Unsupported time windows: Time windows cannot have an overlap of hours to be run correctly. For example, they can not exist in a same scenario a client that has a time window 9am 12pm and another client with time window from 10am to 1pm. This will be explained when doing the training.

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

PARAMETERS

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
}
]
}
]
}

Response Class (Status 200)

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".

Response Class (Status 200)

Campos Tipo Descripción
status string OK / Error
response JSON[]  
  status string The different status of the scenarios are the following:
    • Geocoding: when addresses are being located
    • Incomplete: when data is missing in order to do the optimization.
    • Ready: when the scenario is ready to be optimized.
    • Queueing: when the scenario is waiting to be optimized.
    • Optimizing: when the scenario is being optimized.
    • Cancelled: when the optimization is cancelled.
    • Repairable: when there are orders that cannot fit on the vehicles or if there is not enough time to deliver some orders
    • Error: when there is an error in the optimization.
    • Infeasible: when a solution is not found.
    • Optimized: when the scenario is optimized
    • Modified: when the scenario is modified from the editor.
    • Approved: when the optimization is approved
  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".

Response Class (Status 200)

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".

Response Class (Status 200)

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:

  • assigned: has the results of the vehicles assigned
  • unassigned: has the result of the vehicles that were not assigned
  • infeasible: has the unfeasibles orders

Response Class (Status 200)

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 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"
      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".

PARAMETERS

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
}
}
]

Response Class (Status 200)

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".

Response Class (Status 200)

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"

Response Class (Status 200)

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"
}
}
}
]
}
$(document).ready(function() { $('.collapse').on('show.bs.collapse', function() { var id = $(this).attr('id'); $('a[href="#' + id + '"]').closest('.panel-heading').addClass('active-faq'); $('a[href="#' + id + '"] .panel-title span').html(''); }); $('.collapse').on('hide.bs.collapse', function() { var id = $(this).attr('id'); $('a[href="#' + id + '"]').closest('.panel-heading').removeClass('active-faq'); $('a[href="#' + id + '"] .panel-title span').html(''); }); });