Visits

The visits object is a hash of each visit and their properties, where the key is the visit ID. 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.

"visits": {
  "order_1": {
    "location": {
      "name": "6800 Cambie",
      "lat": 49.227107,
      "lng": -123.1163085
    },
    "start": "9:00",
    "end": "12:00",
    "duration": 10,
    "load": 1,
    "type": "A",
    "priority": "high"
  }
}

👍

Address geocoding

If you don't want to specify the latitude and longitude of the location object, you can also send the full address and Routific will geocode it for you.

"location": {
      "name": "Routific World Headquarters",
      "address": "555 W Hastings Street, Vancouver, BC V6B4N6, Canada"
    }

If our server is unable to locate an address, our API will return a failedGeocoding object (an array of strings) specifying which visits were unable to be geocoded.

"output": {
		"failedGeocoding": ["123 Routific Avenue"],
		"message": "Failed to geocode some locations"
	}

Address geocoding only works on our /vrp-long and /pdp-long endpoints.

🚧

Special characters in IDs

The API will reject requests containing the characters . or $ in the IDs of the visits or fleet.

Each visit can have a time-window constraint, defined by start and end. Time windows are optional; when they are not provided, it implies that any time will do. You can also say "anytime after 9am" by setting the start time to 9:00 and omitting the end parameter.

duration specifies how many minutes the visit takes. If a delivery takes 30 minutes and is given a time-window of 12:00-13:00, the algorithm will make sure that you arrive by 12:30 at the latest. Note that if the duration does not fit in the time-window, the visit will not be assigned to any vehicle. It is good practice to always specify a duration. If you don't, the engine will not return estimated arrival times for each visit.

📘

Pro tip:

The duration parameter may be used as a buffer parameter to accommodate for real-life delays such as parking and traffic lights, and thus avoid arriving late at a location. The only drawback of using too large a buffer, is that it leaves the algorithm less room to optimize.

You may also want to consider simulating slow traffic, see the traffic parameter below.

load is used when you want to account for the capacity of your vehicles. This capacity must be defined with your fleet as well, otherwise this parameter will be ignored.

📘

Multiple loads & capacities

You may also specify multiple load parameters if you provide an object. This is useful if you define your load across multiple dimensions, for example weight and volume:

"load": { 
  "weight": 10,
  "volume": 200
}

The entire load has to fit in the remaining vehicle capacity for it to be assigned. Now you can distinguish heavy goods that are small from large goods that are light :)

Another way to use multiple loads is to specify product-level details:

"load": {
  "large_item": 1,
  "small_item": 5,
  "other_stuff": 2
}

Note that if you specify multiple loads, these loads need to correspond with the capacity parameter in the vehicle object. If not, they will be unserved with the message "The loads cannot fit in any vehicle."

type is an optional parameter if you want to restrict a visit so it can only be served by a particular type of vehicle. The value of this parameter can be a String or an Array of Strings for multiple types. For example, if a visit is of type ["A","B"] it can be served by a vehicle of type "A" or "B". If none of the vehicles match the type, it will be unserved. Visits without any type parameters can be served by vehicles with or without a type associated with it.

priority allows you to make certain visits a priority over others. In some cases you have more visits than you can serve, resulting in a few unserved. But if you want to make sure your high priority visits take precedence, use this parameter and set it to "high".

For more control, you can also specify a priority number between 1 and 10,000. Visits with a higher priority number will take precedence over the lower priority visits. So if you have a visit (A) that has a priority level of 10 and is far away, and 3 other visits (B, C, D) with priority level 5 that are close by, then in a situation where you can feasibly visit either A or (B + C + D), the solution Routific will return is the latter, because the total combined priority score is 15.

If instead you wanted visit A to be served while discarding B, C, and D, then you'll need to increase the priority number for A.

Just for reference: "low" corresponds to 1, regular is 5, whereas "high" maps to 10.

📘

Second time-window

You can also specify two time-windows using the time_windows parameter instead of start and end. This is especially useful if you need to avoid delivery between a certain time. For example, the delivery should happen between 9:00-12:00 OR between 13:30-18:00.

You can specify this as follows:

"time_windows": [
    {
      "start": "09:00",
      "end": "12:00"
    },
    {
      "start": "13:30",
      "end": "18:00"
    }
  ]

Note that the time_windows array needs to be in chronological order.

If you want to send notes to a driver for a given visit (e.g. the number of packages in an order or delivery instructions), you can add add a notes parameter to the visits object. These notes will be preserved in the json returned by the Routing Engine and will be displayed on our web and driver apps if you have an API integration enabled with Routific.

👍

Custom notes (new)

If you want to add additional information such as weight or price to a visit, you can also create a custom notes parameter and add it to the visits object. Just as with the notes parameter, this information will be shown on our web and driver apps if you have an API integration with Routific (Contact support if you want to enable an API integration).

"customNotes": {
   "weight": "100 kg",
   "price": "$50"
}