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
