Response

The MARE routing API returns the best solution found for your problem along with a great number of details about the solution. The idea is to return a solution a solution with every property available so that you do not have to recompute any properties of the routes or solution.

Key	Type	Description
total_distance	double	Sum of total distance traveled in meters across all the routes.
total_travel_time	double	Sum of the total travel time in seconds across all of the routes.
total_traffic_time	double	Sum of estimated total traffic time in seconds across all the routes.
objective_function	double	“Score” of the solution according to the constraints and penalties provided with the problem specification.
solve_time	double	# seconds required for MARE to solve the problem
num_visits_routed	int	The number of stops at orders in the solution (possibly different from the number of unique orders visited in case some orders require multiple visits).
bounding_box	object	The bounding box for the routes in the solution, given as latitude and longitude values.

routes	Array of routes objects	Each route object corresponds to a vehicle shift, and contains time spent traveling, driving directions, polylines, arrival times, and so on.
vehicles	Array of vehicle objects	Contains the vehicles, attributes, and shifts used in the problem
orders	Array of orders objects	Obviously much of this information is redundant and contained in the routes object. However, this object includes information about non-routed orders, and if an application wants to quickly find an order and its status, this offers a more convenient representation of the data.
constraints	Array of objects	This has a detailed list of the constraints violated in the problem.
orders_incomplete_visits	Array of objects	For all the orders where the solution does not meet all the visit requirements, this provides some info into why these orders were possibly not visited (round trip travel times to start/end locations, etc.)

bounding_box Object

Useful for plotting the polylines contained in the response.

Key	Type	Description
max_lat	double	Maximum latitude of the bounding box.
max_long	double	Maximum longitude of the bounding box.
min_lat	double	Minimum latitude of the bounding box.
min_long	double	Minimum longitude of the bounding box.

routes Object

Key	Type	Description
route_id	string	MARE-assigned string guaranteed to be unique within this response.
route_start_time	string	ISO string of the route start time
abs_route_start_time	int	Unix timestamp of the route start
route_end_time	string	ISO string of the route end time
abs_route_end_time	int	Unix timestamp of the route end
route_travel_time	double	Total travel time in seconds fo the route.
route_working_time	double	Total travel time plus additional time spent servicing and idling during the route.
total_idle_time	double	Total number of seconds spent in idle time waiting for a break or waiting to meet a time window.
slack_time	double	Total number of seconds of “unused” time in the route.
route_traffic_time	double	Estimate of the total time spent in traffic. This is computed by taking the difference of actual travel time and the lowest travel time amount on any of the route segments.
total_break_time	double	Total number of seconds spent in a break on the route.
num_breaks	int	Number of breaks on the route.
breaks	Array of break objects	The breaks included in this route.
total_soft_break_time	double	Total number of seconds spent in a soft break on the route.
num_soft_breaks	int	Number of soft breaks in the route.
soft_breaks	Array of soft_break objects	The soft breaks included in this route.
num_floating_breaks	int	Number of floating breaks in the route.
total_floating_break_time	double	Total number of seconds spent in a floating break on the route.
floating_breaks	Array of floating_break objects	The floating breaks included in this route.
start_location_id	string	ID of the location of the first stop on the route.
end_location_id	string	ID of the location of the last stop on the route
max_segment_time	double	Number of seconds in the longest segment on this route
max_segment_distance	double	Number of meters in the longest segment on this route
max_volume_in_vehicle	double	The maximum volume of the items in the vehicle over the entire route
max_weight_in_vehicle	double	The maximum weight of the items in the vehicle over the entire route
items_delivered	Array of objects	Each object give the item_type and total quantity of that item delivered on the route
items_picked_up	Array of objects	Each object give the item_type and total quantity of that item picked up on the route
itinerary	Array of objects	Each object describes the sequence of actions taken on the route (i.e. driving, servicing order, break, soft break) with a start and end time of each event type
polylines	Array of strings	Provides information necessary to plot the route on a digital map
directions	Array of strings	Driving directions for the route. These are in the same format as OSRM.

break Object

Key	Type	Description
breaks.abs_break_start_time	double	Absolute time of break start.
breaks.abs_break_end_time	double	Absolute time of break end.
breaks.break_start_time	double	ISO 8601 time string of break end.
breaks.break_end_time	double	ISO 8601 time string of break end.

soft_breaks Object

Key	Type	Description
soft_breaks.abs_break_start_time	double	Absolute time of soft break start.
soft_breaks.abs_break_end_time	double	Absolute time of soft break end.
soft_breaks.break_start_time	double	ISO 8601 time string of soft break start.
soft_breaks.break_end_time	double	ISO 8601 time string of soft break end.

floating_breaks Object

Key	Type	Description
floating_break.abs_break_start_time	double	Absolute time of soft break start.
floating_break.abs_break_end_time	double	Absolute time of soft break end.
floating_break.break_start_time	double	ISO 8601 time string of floating break start.
floating_break.break_end_time	double	ISO 8601 time string of floating break end.

orders Object

Key	Type	Description
orders.order_id	string	String representing order (matches exactly what is passed in at the input, likely a fully specified address but can be anything guaranteed to be unique)
orders.arrival_time	string	ISO 8601 string representing arrival time at the stop (NULL string if not routed).
orders.abs_departure_time	int	The absolute departure time of this order.
orders.departure_time	string	The actual departure time of this order.
orders.latitude	double	The latitude of this order.
orders.longitude	double	The longitude of this order.
orders.abs_arrival_time	int	Unix timestamp of arrival time at the stop (0 if not routed)
orders.route_id	string	The ID of the route containing the order. NULL if order is “unrouted”
orders.position_in_route	int	position that the order is visited in the route. The starting location of the route is position 0. If not routed, then value of -1 is given,
orders.service_time	int	The time spent servicing the order.
orders.status	string	“Routed” if contained in a route, “unrouted” otherwise.
orders.order_index	int	Internal index of the order (used for debugging only)

constraints Object

MARE returns information about the Constraints that are violated in the solution. For constraints where this violation can be isolated to a single order (such as a violated time window), the relevant order_ids are also returned.

Errors

All MARE errors return a JSON response with a human readable comment describing the issue. Depending on the error returned, there may be additional objects to further describe the error. Below is a partial list of errors currently handled by MARE.

JSON Parse Error
Missing Object
Radius < 0
No Vehicle Shift
Shift Missing Start and End times
Invalid Pickup Item Type
Invalid Delivery Item Type
Duplicate Location ID
Location ID in Order Not Found
Traffic Windows Errors
Invalid Time Zone
Invalid Time Window Start / End
Invalid Appointment Start / End
Duplicate Order Id
Duplicate Items
Invalid Start Location ID
Invalid End Location ID
Break Start Length != Break End Length
Break Start Length != Break End Length
Soft Break Start Length != Soft Break End Length
Missing Constraint Type
Missing Constraints