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.

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_id and quantity. The item_id must be contained in the upper level “items” object.

Default: If this is not provided, then MARE will not account for any pickups.

Refer to the example to get started quickly.
delivery_item_quantities
Array of items objectsYIdentical format to pickup_item_quantities.

Refer to the example to get started quickly.
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).
appointmentsArray 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_gapintYMinimum 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.

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 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 cubic centimeters that the vehicle can carry.
weight_capacitydoubleYMaximum kg that the vehicle can carry.
hazmatbooleanYTrue if this vehicle is carrying a load of hazardous material and should be routed accordingly.

Default: If not provided, MARE assumes the load is not limited by hazmat restrictions.
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.

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.