Parameters

The JSON request to the routing endpoint consists of the following objects.

KeyTypeOptionalDescription
locations
array of location objects
NThe locations for this routing request.
orders
array of order objects
NRepresents the requests for services. Can be a set of multiple requests for service over an entire period or just one request for service.
vehicles
array of vehicle objects
NDescribes the set of vehicles and their attributes that may be used to solve the problem. Currently, all vehicles must be of the same type (car, truck, bike, or pedestrian).
constraints
array of constraint objects

NThe constraints describe the specifics of what makes a “good” solution to the problem given all the data about the problem from the locations, shifts, orders, and vehicles. The mixture of constraints and penalties work together to produce a solution to the problem that should satisfies the different objectives.
itemsarray of item objects
YThe items to be picked up and / or delivered in this routing problem. For example, a truck may pick up a load of bricks from one location and deliver it to another. This parameter is only used to describe the characteristic of the items, not quantities or capacities. You can specify those on a per-vehicle and per-order basis in the request.

Default: If nothing is provided, MARE will not take into account any pickups, deliveries, or vehicle capacities. 

Refer to the example to get started quickly.
rounding_minutesintYIf provided, then all service start times will be rounded up to the nearest rounding_minutes time. For example, if rounding_minutes = 30, then all service events at orders will start at a time of hh:30 or hh:00 for some hh. To achieve this, the vehicle may be required to idle at stops before starting the service, but this can be convenient for cases where the customer at the stop must be notified of the visit time as a time like 15:11:34 may be too precise for practical purposes.

location

KeyTypeOptionalDescription
latitude
double
NThe latitude of the location.
longitude
double
NThe longitude of the location.
location_id
string
NUnique string ID for this location.

order

KeyTypeOptionalDescription
order_idstringNList of attributes that may be used to describe an affinity between items and orders or vehicles.

location_idstringNID of the location for this order.
pickup_item_quantities
Array of items objectsYArray of items that specify an item_type and quantity. The item_type must be contained in the upper level “items” object.

Refer to the example to get started quickly.
dropoff_location_idstringYTypically, any items picked up on a route are carried on the vehicle until they are unloaded or the route terminates. However, for cases such as passenger pick up and dropoff, we may wish to drop off these items somewhere else and then have the route continue. This is done by specifying a dropoff_location_id for the order. If provided, then any solution returned by MARE that visits this order and picks up the items will also include an additional stop in the same route where the items are dropped off at the specified location.
delivery_item_quantities
Array of items objectsYIdentical format to pickup_item_quantities.

Refer to the example to get started quickly.
unloading_capacity_by_item
Array of items objects
YIf an order represents an unloading facility, then this should specify the total amount by item type that all vehicles can unload at this order. In most cases, this will be an unlimited amount and should be set to a very large value that will never be reached. Note that a large value of max_visits should also typically be set for an unloading order. For more details, see this example.
replenishment_capacity_by_item
Array of items objects
YIf an order represents a replenishment facility, then this should specify the total amount of each item type that can be picked up across all vehicles at this stop. If unlimited replenishment is available, then this should be set to very large values for each item type. Note that a large value of max_visits should also typically be set for a replenishment order.
durationintYThe duration in seconds of the time required to service this order.

Default: If this is not provided, then we assume the order is satisfied instantaneously (duration is 0).
appointmentArray of appointments objectYThe start and end times for fixed appointments. Note that when an appointment is provided, the duration parameter of the order (if given) is ignored when MARE schedules the appointment(s). Appointments are enforced with the Scheduled_Appointment constraint.
time_windowsArray of
time_windows objects
YIf not given, MARE assumes this order can be visited during any shift of the problem. If given, then this tells us the range of allowable arrival times at this order. Note that MARE may decide that a vehicle will idle before visiting this order depending on the Time_Window constraint and penalty.
attributesArray of stringsYList of arbitrary attributes associated with the order to create an affinity between vehicles and orders. Examples would be “only likes Jim”, “needs anesthesia car”, “Spanish only”, etc. These strings must exactly match with the vehicle attribute parameters, and are enforced via the Match_Attributes constraint.
min_visitsintYMinimum number of visits this order must receive over the planning period (defaults to 1). Enforced via the Visit_Range constraint.
max_visitsintYMaximum number of visits this order must receive over the planning period (defaults to 1). Enforced via the Visit_Range constraint.
min_daysintYMinimum number of days between visits. Enforced via the Visit_Gap constraint.
urgencyintYMust be between 1 and 99. When coupled with the Urgency constraint, a penalty is incurred when the order is not visited early enough in the planning period.
priorityintYSome positive integer representing the importance of this order relative to others. To be enforced, must also specify Order_Priority constraint.

Default: All priorities are set to 1, and all orders are assumed to have an equal weight. If some orders have priorities and others do not, then orders without a priority will default to 1. To encourage an order to be visited, set a priority > 1 and use the Priority constraint.

appointment (optional)

KeyTypeOptionalDescription
appointment_startstringNLocal start time given in ISO8601 time format. Used in conjunction with `appointment_end` parameter. Example: “2018-10-02T12:30:00-04:00”
appointment_endstringNLocal end time given in ISO8601 time format. Used in conjunction with `appointment_start` parameter. Example: “2018-10-02T14:30:00-04:00”

time_window (optional)

KeyTypeOptionalDescription
start_time_windowstringNThe start time, given as an ISO 8601 time format.
end_time_windowstringNThe end time, given as an ISO 8601 time format. Note that supplying only time windows with orders is not sufficient to enforce them. One must also include a time window constraint for them to be honored.

vehicle

KeyTypeOptionalDescription
shiftsArray of shift objectsNEach entry describes the start and end location, shifts and breaks of the vehicle during the problem. A vehicle is allowed to be traveling and servicing orders only during some shift. Shifts cannot overlap for a given vehicle. Values for start_location_id and end_location_id are optional – if not specified then the route is “open” in the sense that the optimization will determine the best starting and ending location.
vehicle_idstringNString identifier of the vehicle, “John’s Truck”.
volume_capacitydoubleYMaximum volume capacity that the vehicle can carry. Note that the units of volume are irrelevant as long as they match the weight units used for items.
weight_capacitydoubleYMaximum weight that the vehicle can carry. Note that the units of weigh are irrelevant as long as they match the volume units used for items.
hazmatbooleanYTrue if this vehicle is carrying a load of hazardous material and should be routed accordingly. Only valid with vehicle type “truck”

Default: If not provided, MARE assumes the load is not limited by hazmat restrictions.
weight_per_axledoubleYMaximum weight per axle of the truck. Only valid with vehicle type “truck”
num_axlesdoubleYUsed to describe truck properties in order to restrict routing to allowable roads.
capacity_by_itemarray of item/quantity pair objectsYDescribes a set of (item_type, value) pairs that the vehicle can carry. Each key must be an item_type given in the “items” object. If this is not given, MARE assumes the vehicle has an infinite capacity on a per-item basis. Mixing different items is handled by volume_capacity, in cubic meters or weight_capacity in kg.

Default: If not given, MARE will not take into account any capacities by item.
lengthdoubleYmeters
widthdoubleYmeters
weightdoubleYkilograms
heightdoubleYmeters
typestringYCan be one of “car”, “truck”, “bike” or “pedestrian”. 


Default: If not given, MARE defaults to car.
attributesArray of stringsYList of named attributes associated with this vehicle, for example, “bucket truck”, “Spanish speaking”, etc. This is used to create an affinity between vehicles and orders.

Default: If not provided, MARE’s solution will not be influenced by attributes. If provided then either the match attributes or avoid attributes constraint will influence the impact of attributes on the solution.

shift

KeyTypeOptionalDescription
shift_idstring
NA unique identifier for the shift.
example “Tuesday Polishing or Painting”
shift_startstringNStart local time given as an ISO8601 time format. Used in conjunction with shift_end parameter.
example: “2018-10-02T12:30:00-04:00”
shift_endstringNEnd local time given as an ISO8601 time format. Used in conjunction with shift_start parameter.
example: “2018-10-02T12:30:00-04:00”
start_location_idstringYUnique identifier for the starting location of the vehicle; must be identical to a location in the locations array.
example: “location-a”
end_location_idstringYUnique identifier for the ending location of the vehicle; must be identical to a location in the locations array.
example: “location-b”
break_startarrayYAn array of the break start times given in ISO8601 time format. Used in conjunction with break_end array.
example: [“2018-10-02T09:00:00-04:00”]
break_endarrayYAn array of the break end times given in ISO8601 time format. Used in conjunction with break_start array.
example: [“2018-10-02T10:00:00-04:00”]
soft_break_startarrayYAn array of the soft break start times given in ISO8601 time format. Used in conjunction with soft_break_end array.
example: [“2018-10-02T09:00:00-04:00”]
soft_break_endarrayYAn array of the soft break end times given in ISO8601 time format. Used in conjunction with soft_break_start array.
example: [“2018-10-02T10:00:00-04:00”]
floating_break_window_startstringYStart local time given as an ISO8601 time format. Used in conjunction with shift_end parameter.
example: “2018-10-02T12:30:00-04:00”
floating_break_window_endstringYEnd local time given as an ISO8601 time format. Used in conjunction with shift_start parameter.
example: “2018-10-02T12:30:00-04:00”
floating_break_durationintYThe duration in seconds of the time required to service this order. If this keyword is not provided, MARE assumes the order is unrealistically satisfied instantaneously.
example: 3600
home_location_idstringYAn optional specification of a location_id for the home of the vehicle for this shift. This can be used in conjunction with the Max_Commute constraint or the Home_Radius constraint to control how the stops on a shift relate to this home location.

item (optional)

KeyTypeOptionalDescription
item_type
string
NString that identifies the type of item. For example, “lumber” or “frozen meat”.

Refer to the example to get started quickly.
volumedoubleYCubic centimeters of space taken up by the item.
weightdoubleYWeight of the item in kilograms.


attributesArray of stringsYList of attributes that may be used to describe an affinity between items and orders or vehicles.

item/quantity (optional)

KeyTypeOptionalDescription
item_typestringNEach item type must be an item_type given in the “items” object.
quantityintegerNA value representing the number of items this vehicle can carry.

constraint

Refer to the Constraints page.

forced_routes (optional)

If some routes are already determined and are to be locked in place, then this can be achieved by adding a “forced_routes” object. In this case, the sequence of stops is taken as input and MARE simply computes the travel time, polylines, and driving directions for this sequence. Breaks and soft breaks are also placed into the route if they exist in the input and constraints are evaluated. However, there is no attempt to improve the route even if it can be easily made more efficient. See the examples for more details.

KeyTypeOptionalDescription
shift_idstringNThe id of the shift which will have forced_stops.
stopsarray of stop objectsNA stop object, which consists of a stop type and an id.

stop

KeyTypeOptionalDescription
stop_typestringNThe type of stop – either “order” or “location”
stop_idstringNThe ID corresponding to the stop – should be the order_id if the stop is an order, and the location_id if the stop type is location.