Visits

How to Use the Visits Object

The visits object is a hash of each visit (also commonly referred to as a "stop") and their properties, where the key is the visit ID. For most logistics companies, this key will be the unique reference number used to identify the purchase or delivery order associated with the visit. Each visit object has to contain a location object with the geographic coordinates (lat and lng). Note that the name parameter in the location object is optional.

JSON

"visits": {
    "ABC-123": {
      "location": {
        "name": "Brassneck Brewery",
        "lat": 49.2657714,
        "lng": -123.1017201
      },
      "start": "18:00",
      "end": "19:00",
      "duration": 30,
      "load": 1,
      "type": ["downtown-vancouver"]
    }
}

Visits Object

Field	Type	Notes
location	Object	required
start	String ("hh:mm")	optional
end	String ("hh:mm")	optional
duration	Number (minutes)	optional
load	Number (any unit)	optional
type	Array	optional
priority	Number (1 is highest)	optional

location is an object that provides the exact GPS coordinates of the visit. It consists of a lat and lng field for the latitude and longitude of the visit as well as an optional name field that should be used to easily identify the location e.g. "Brassneck Brewery". This assumes that the addresses for each visit are geocoded (perhaps by using the Google Maps API) before being sent to the routing engine. If you need our route optimization engine to handle geocoding as well, this is something that can be built as a custom feature. Please contact us to receive information on pricing and availability.

Location Object

Field	Type	Notes
name	String	optional
lat	Number	required
lng	Number	required

start is a string in "hh:mm" format e.g. 09:00 that indicates the start time window of the visit. For example, if you are delivering to a business and want to make sure your driver only arrives there during business hours, you could use "start": "10:00" to guarantee that the route optimization algorithm schedules this visit after 10 am.

end is a string also in "hh:mm" format e.g. 17:00 that indicates the end time window of the visit. For example, if you are delivering to a business and want to make sure your driver only arrives there during business hours, you could use "end": "17:00" to guarantee that the route optimization algorithm schedules this visit before 5 pm.

If you need to route over two days or more, you can use military time to indicate start andendtime windows that extend past 24 hours e.g. use "30:00" (which is 24:00 + 06:00 hours) for 6 am the next day.

duration is a string representing the time in minutes that the driver will spend at the visit location (default value: 0 minutes). For example, if on average your drivers spend 10 minutes making a delivery, you should use "duration": 10 to ensure that the routing engine allocates 10 minutes to that visit.

If you need to take into account that the durations for multiple deliveries to the same location do not add up linearly, you can use our squash durations feature. For example, if the duration of each visit is 10 minutes but each additional visit to the same location only takes 1 minute, just add squash_durations: 1 to the options object in the input. If there are 6 deliveries to the same location (as defined by the latitude and longitude of the visit) the total duration will be 10 + 1 + 1 + 1 + 1 + 1 = 15 minutes.

load refers to the size of the package(s) your driver is delivering and is measured relative to the capacity of the vehicle he is driving. For example, if his vehicle can safely carry 100 kg of packages and each package weighs 10 kg on average, the routing engine will use this information to ensure that the driver will never be assigned more than 10 deliveries. You can also use this feature to balance package volume equally across your vehicle fleet. Simply set the load on each package to 1 and set up your fleet (vehicle) objects with a capacity equal to the total number of packages divided by the number of available vehicle e.g. if you have 100 packages and 20 vehicles, set the capacity of each vehicle to 5.

Loads and capacities can also be a vector i.e. you can ask the routing engine to consider multiple loads and capacities when coming up with a route solution. For example, suppose you run a rideshare service and want to be able to pick up both people and packages. You could set:

"load": { "people": 1 }

on the visits object and:

"capacity": { "people": 1, "packages": 10 }

on the fleet object. This ensures that the each vehicle will never carry more than 1 person or 10 packages at a time.

type allows you to match drivers (as defined in the fleet object) with specific skills to visits of a specific type. For example, you might want to ensure that visits in downtown Vancouver are only served by drivers with the necessary expertise to drive and easily find free parking there. To do this, you could set:

"type": ["downtown-vancouver"]

on the visits object and:

"type": ["downtown-vancouver"]

on the fleet object. Here's what the full json input looks like:

{
  "visits": {
    "ABC-123": {
      "location": {
        "name": "Brassneck Brewery",
        "lat": 49.2657714,
        "lng": -123.1017201
      },
      "start": "18:00",
      "end": "19:00",
      "duration": 30,
      "load": 1,
      "type": [
        "downtown-vancouver"
      ]
    }
  },
  "fleet": {
    "vehicle_1": {
      "start_location": {
        "id": "driver_start",
        "name": "Killarney, East Vancouver",
        "lat": 49.2287301,
        "lng": -123.0421047
      },
      "end_location": {
        "id": "driver_end",
        "name": "VanDusen Botanical Gardens",
        "lat": 49.2385564,
        "lng": -123.1309102
      },
      "shift_start": "17:00",
      "shift_end": "23:00",
      "capacity": 10,
      "type": [
        "downtown-vancouver"
      ]
    }
  },
  "options": {
    "polylines": true
  }
}

This doesn't always guarantee that there will be a match - you also need to consider driver shift times, time windows, vehicle capacities and other constraints. However, if no vehicle is assigned to the visit because it could not find one with the appropriate skill, you'll get an error message: The types do not match with any vehicle.

priority allows you to ensure that within reason, visits of a higher priority will take precedence over visits of lower priority i.e. the routing engine will do its best to make sure that high priority visits are served. priority is an integer number (lower is better) that starts at 1 (highest priority). Here's how it works - the routing engine calculates the top 100 route solutions. It then selects the route solution that has the fewest number of priority 1 visits unserved (even if the total distance travelled by the vehicle fleet in this route solution is higher than the others). If more than one solution has the same number of priority 1 visits unserved, it will chose the solution with the least number of priority 2 visits unserved, and so on. Ties are decided by choosing the route solution with the least total distance travelled.