A new API that optimises multiple itineraries for field and logistics operations
Blog|by Jamie Maguire|20 November 2019
Microsoft recently shipped a new API that belongs to the Bing Maps family, the Multi-Itinerary Optimization API (or MIO for short). The MIO API is ideal if you’re battling with delivery planning and schedule issues as it helps you plan an itinerary schedule for one or more agents that need to travel between multiple locations and itinerary items.
For example, couriers that have multiple delivery locations that work multiple shifts, e.g., morning and afternoon – with this information, the MIO API can return the following information for each agent/courier:
- Delivery location(s)
- Expected duration(s)
- Optimised itinerary order of stops and itinerary detail(s)
Features
The MIO API can take an optional parameter of priority for each itinerary item. The priority value can be from 1 to 100, with the larger number indicating a higher priority. The API will prioritise the itinerary items with higher priorities and try to maximise the sum of the priorities of the schedulable itinerary items such as capacity, agent shifts, dwell time. If all items have a priority of 1 (which is the default value), the API will then maximise on the number/count of scheduled items.
You also have the option of setting additional parameters based on your unique business requirements. For example, the costvalue parameter can be set to either TravelTime or Distance. Setting this parameter lets you minimise the travel time or distance travelled for the scheduled items that need to be delivered.
How can you consume the MIO API?
Like other APIs in the Bing ecosystem, you can consume the MIO API by issuing a GET or POST request. When forming a POST request to consume the MIO API you need to provide specific information about each agent and the respective itinerary items. (POST is ideal for larger requests.)
Below you can see the key parameters that you need to supply for both agent and itinerary items. For a full list, go to the Microsoft Docs site.
Agent Information
- Name
- Agent shift information; for each shift:
- Shift ending time
- Shift starting time
- Shift starting location (Query or Point)
- Shift ending location (Query or Point)
- Capacity (vehicle capacity)
Itinerary Items
- Delivery/visit duration, called “dwell time”
- Business opening time
- Business ending time
- Location (Query of Point)
- Item Priority (on a scale from 1 to 100, from lowest to highest)
- Quantity (corresponds to Agent Capacity)
- DropOffFrom (force an itinerary stop to be visited before another specific itinerary stop)
- Itinerary Name (Company name)
So, what would this data look like? Let’s look at an example of this data for both agents and itinerary items.
An Example
Agent Data
Imagine you have two agents, Connor and Harris. Both agents have one shift. Each of these agents also have:
- 1 starting location
- 1 starting time
- 1 end location
- 1 end time
Connor delivers packages from 0900 to 1700 and takes a lunch break of 60 minutes at 1200. This would mean that Connor would have two shifts. The first being from 0900 to 1200 and the second being from 1300 to 1700.
To keep things simple, we will assume that both agents will take their lunch break at the same location which is: Falcons Nest, Gosforth, Rotary Way, Newcastle Upon Tyne NE3 5EH (or 55.035340, -1.625570 in coordinates). For convenience, you can see the following table which contains both our agents’ starting and ending information:
Shift Data
The following tables and maps show per agent start time, start co-ords, end time and end co-ords. The circles indicate the following:
- green circle: the starting location
- red circle: the ending location
- yellow circle: where lunch is being taken (55.035340, -1.625570)
Connor’s details:
Harris’s details:
Formatting Itinerary Data
Finally, we need to set the itinerary data. To simplify this, we’ll factor the following into our example:
- All delivery locations will have the same opening and closing hours
- We will only assign seven items to each agent
We’ll assign different priorities and dwell times to each drop off.
The table below contains the list of destinations and their respective co-ordinates, dwell time and priority.
By this point, we’ve got the agent shift data along with the respective itinerary items. We can now create a request in Postman and test the endpoint.
Creating the request in Postman
Using the information we’ve just formatted, we can construct the following POST request body:
After submitting the request to the MIO API using Postman, the following JSON is returned:
Using the Callback URL
In the above response, you can see a callbackUrl. Clicking on this will construct a new request that points you to a new URL which contains the most optimal routes for both agents the MIO API has generated:
Click Send.
Parsing the MIO API Response
(Spoiler warning – the response payload contains quite a bit of data!)
After clicking send on the callbackUrl, the MIO API returns the following data:
Key Nodes in the Response
The key nodes to pick out in the above response are:
Instruction Type: The instruction type for the agent. This can be either: LeaveFromStartPoint, TravelBetweenLocations, VisitLocation, ArriveToEndpoint.
Distance:The estimated distance in metres.
Duration: The estimated travel time. This applies only for the instructions: TravelBetweenLocations.
To recap, to invoke the API we have:
- Set up agent data.
- Assigned itinerary and shift items.
- Created and invoked the MIO API using data from #1 and #2.
- Taken the callbackUrl from the MIO API initial response, then used that to return the optimised route.
You’ve got an optimised route but now what?
Use Cases
With the data optimised and categorised in this way you can do quite a few things with it. For example, you can take the generated latitudes and longitudes and plot directions on a Bing Map.
In this example, I’ve taken the first couple of steps from Connor’s journey (our agent from the earlier example) and used the Directions Module that ships with the Bing Maps SDK to then plot the directions on a web page that contains a Bing Map:
You’re probably having your own ideas as to how the MIO API can be deployed, some other ideas include but aren’t limited to:
Sales Reps: Optimise the routes sales reps should take.
Local Authorities: Use the MIO API to help you easily plan out an itinerary of maintenance repairs.
Safety Inspections: Safety inspections of local businesses can use the MIO API to plan the most optimum journey for site visits.
Delivery Drivers: We’ve just seen an example of this throughout this blog post.
Summary
In this blog post we’ve introduced the Bing Maps MIO API. We’ve seen how you can use it to help you take the complexity out of multi-schedule and multi-route planning when it comes to determining the most optimal routes for your field or logistics operations.
We’ve also seen how the API can provide you with a breakdown of step by step instructions and datasets that lend themselves to being easily plotted on to mapping technologies such as Bing Maps.
You can find out more about the MIO API here.
You’ll need a Bing Maps key to the MIO API, get a free one here.
Check out the Bing Maps MIO API demo on their website here.
If you need more information about Bing Maps, geocoding, or integrating the MIO API into your app, the Grey Matter mapping team are map and licensing specialists and can be contacted on: mapping@greymatter.com or called directly on +44 (0)1364 655 133.
Contact Grey Matter
If you have any questions or want some extra information, complete the form below and one of the team will be in touch ASAP. If you have a specific use case, please let us know and we'll help you find the right solution faster.
By submitting this form you are agreeing to our Privacy Policy and Website Terms of Use.
