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.

KeyTypeDescription
total_distancedoubleSum of total distance traveled in meters across all the routes.
total_travel_timedoubleSum of the total travel time in seconds across all of the routes.
total_traffic_timedoubleSum of estimated total traffic time in seconds across all the routes.
objective_functiondouble“Score” of the solution subject to the constraints provided with the problem specification.
num_orders_routedintThe number of orders routed in the solution.
bounding_boxobjectThe bounding box for the routes in the solution, given as latitude and longitude values.
routesArray of routes objectsEach route object corresponds to a vehicle shift, and contains time spent traveling, driving directions, polylines, arrival times, and so on.
vehiclesArray of vehicle objectsContains the vehicles, attributes, and shifts used in the problem
ordersArray of orders objectsObviously 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.
constraintsArray of objectsThis has a detailed list of the constraints violated in the problem.
orders_incomplete_visitsArray of objectsFor 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.

KeyTypeDescription
max_latdoubleMaximum latitude of the bounding box.
max_longdoubleMaximum longitude of the bounding box.
min_latdoubleMinimum latitude of the bounding box.
min_longdoubleMinimum longitude of the bounding box.

routes Object

KeyTypeDescription
route_idstringMARE-assigned string guaranteed to be unique within this response.
route_start_timestringISO string of the route start time
abs_route_start_timeintUnix timestamp of the route start
route_end_timestringISO string of the route end time
abs_route_end_timeintUnix timestamp of the route end
route_travel_timedoubleTotal travel time in seconds fo the route.
route_working_timedoubleTotal travel time plus additional time spent servicing and idling during the route.
total_idle_timedoubleTotal number of seconds spent in idle time waiting for a break or waiting to meet a time window.
slack_timedoubleTotal number of seconds of “unused” time in the route.
route_traffic_timedoubleEstimate 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_timedoubleTotal number of seconds spent in a break on the route.
num_breaksintNumber of breaks on the route.
breaksArray of break objectsThe breaks included in this route.
total_soft_break_timedoubleTotal number of seconds spent in a soft break on the route.
num_soft_breaksintNumber of soft breaks on the route.
soft_breaksArray of soft_break objectsThe soft breaks included in this route.
start_location_idstringID of the location of the first stop on the route.
end_location_idstringID of the location of the last stop on the route
max_segment_timedoubleNumber of seconds in the longest segment on this route
max_segment_distancedoubleNumber of meters in the longest segment on this route
max_volume_in_vehicledoubleThe maximum volume of the items in the vehicle over the entire route
max_weight_in_vehicledoubleThe maximum weight of the items in the vehicle over the entire route
items_deliveredArray of objectsEach object give the item_type and total quantity of that item delivered on the route
items_picked_upArray of objectsEach object give the item_type and total quantity of that item picked up on the route
itineraryArray of objectsEach 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
polylinesArray of stringsProvides information necessary to plot the route on a digital map
directionsArray of stringsDriving directions for the route. These are in the same format as OSRM.

break Object

KeyTypeDescription
breaks.abs_break_start_timedoubleAbsolute time of break start.
breaks.abs_break_end_timedoubleAbsolute time of break end.
breaks.break_start_timedoubleISO 8601 time string of break end.
breaks.break_end_timedoubleISO 8601 time string of break end.

soft_breaks Object

KeyTypeDescription
soft_breaks.abs_break_start_timedoubleAbsolute time of soft break start.
soft_breaks.abs_break_end_timedoubleAbsolute time of soft break end.
soft_breaks.break_start_timedoubleISO 8601 time string of break start.
soft_breaks.break_end_timedoubleISO 8601 time string of break end.

orders Object

KeyTypeDescription
orders.order_idstringString 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_timestringISO 8601 string representing arrival time at the stop (NULL string if not routed).
orders.abs_departure_timeintThe absolute departure time of this order.
orders.departure_timestringThe actual departure time of this order.
orders.latitudedoubleThe latitude of this order.
orders.longitudedoubleThe longitude of this order.
orders.abs_arrival_timeintUnix timestamp of arrival time at the stop (0 if not routed)
orders.route_idstringThe ID of the route containing the order. NULL if order is “unrouted”
orders.position_in_routeintposition 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_timeintThe time spent servicing the order.
orders.statusstring“Routed” if contained in a route, “unrouted” otherwise.
orders.order_indexintInternal 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