Stops

The stops object is an array of stop objects that describe the properties of a stop. Each stop object has to contain a location object with the geographic coordinates (lat and lng) inside a coords object. If the ​coords​ are not included in the input, Routific will try to geocode the addresses from the ​address​ field. If c​oords​ are included, the app will use the ​coords​ and skip the geocoding process.

JSON

"stops": [{
	"name": "Jane Doe",
	"location": {
		"address": "2148 Main St, Vancouver, BC V5T 3C5",
		"coords": {
			"lat": 49.2657634,
			"lng": -123.1004459
		}
	},
	"start": "10:00",
	"end": "11:00",
	"duration": 20,
	"types": ["a"],
	"load": 1,
	"priority": true,
	"phone_number": "[phone]",
	"email": "[email protected]",
	"notes": "Press 304 at buzzer.",
	"custom_notes": {
  	"orderId": "ABC123"
  }
}]

PROPERTY	TYPE	NOTES	Description
name	String	required	The name of the stop, typically your customer’s name.
location	Object	required	Allows you to define the physical location of each stop. It may contain the geographic coordinates (lat and lng) inside a coords object, otherwise the coordinates will be geocoded for you. Read more.
start	String ("hh:mm")	optional	The start time for this stop's time window constraint. Read more.
end	String ("hh:mm")	optional	The end time for this stop's time window constraint
duration	Number (minutes)	optional	The number of minutes the visit takes. It is good practice to always specify a duration. If you don't, the engine will not return estimated arrival times for each stop. Read more.
load	Number (any unit) or Object	optional	Used to account for the capacity of your vehicles. This capacity must be defined with your fleet as well, otherwise this parameter will be ignored.
types	String or Array	optional	Used to restrict a visit so it can only be served by a particular type of vehicle. Read more.
priority	String (low, regular(default), high) or Number	optional	Allows you to make certain visits take precedence over others. Read more.
phone_number	String ("[phone]")	optional	The phone number of the stop, typically your customer’s phone number to allow the driver to call them or send an SMS.
email	String	optional	The phone number of the stop, typically your customer’s email. By providing this email, your customers can receive update notifications regarding their delivery. Read more.
notes	String	optional	Notes to the driver for a given visit. Read more.
custom_notes	Object	optional	Used for including additional metadata about the visit (ie. order IDs, weight, or price) Read more.

Location

The location payload may contain the geographic coordinates (lat and lng) inside a coords object.
If the ​coords​ are not included in the input, Routific will try to geocode the addresses from the ​address​ field.
If c​oords​ are included, the app will use the ​coords​ and skip the geocoding process.

Time Windows

Each stop 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

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

Types

types 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

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.

Phone Number

phone_number is your customer’s phone number. When you dispatch to your drivers, they can click on the phone number to either call them or send an SMS. Expects a valid phone number in international phone number format (eg. [phone]).

Notes

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

If you want to add additional information such as an order ID, weight or price to a visit, you can also create a custom_notes parameter and add it to the stops object.