Self-improving routes

Introduction

Businesses fulfilling scheduled orders need to plan order routes for drivers. Planning includes batching and sequencing orders for available drivers. Often times such planning must be done in advance, like the day before fulfillment, to share routes with ops managers and drivers. Planning last mile fulfillment depends on multiple factors including business constraints around route distances and duration, driver availability, order scheduled times and locations, etc. HyperTrack Ops Groups, Drivers and Orders APIs let you build workflows for planning to suit your dynamic business needs. Each API lets you manage a distinct part of your workflow independently as described below:

Ops Groups API lets you define business constraints for individual ops groups like store locations, routing constraints etc.
Drivers API lets you define driver profiles and availability,
Orders API lets you call our planning systems with your order book to get routes for available drivers based on the business constraints defined. The Orders API also lets you start tracking orders when they are dispatched and learn from fulfillment ground truth to continually improve planning in the future.

The diagram below provides a high level order planning workflow through the HyperTrack Orders API:

This guide walks you through how you can plan orders with HyperTrack API. Note planning in the HyperTrack context refers to batching and sequencing orders for drivers. This does not start live order tracking automatically. If you have your own order planning system and would like to only leverage live order tracking through HyperTrack please refer to the Live Order Tracking guide.

Getting started

1. Setup ops groups

Ops groups in HyperTrack represent the units around which your business operations are structured and are managed through the Ops Group API. For instance, if your business operates with stores, then each store may be its own operations group.

To setup your Ops groups please refer to this guide.

2. Adding drivers

Drivers in HyperTrack represent members in your fleet and are managed through the Drivers API. To setup drivers please refer to this guide.

To setup your Driver App please visit the Driver App Setup guide and refer to relevant guide depending on the type of Driver app you are using for your fleet.

3. Generating scheduled routes

After setting up your Ops groups and adding Drivers with schedules, the Orders API lets you batch and sequence orders into routes for drivers based on their availability. Here's a sample payload to plan two orders to help you get started:

POST https://v3.api.hypertrack.com/orders


{
  "plan_mode": "scheduled",
  "ops_group_handle": "ops_group_STL",
	"orders": [
        		{
			"order_handle": "order-2023041313_03",
			"scheduled_after": "2023-04-15T01:00:00Z",
			"scheduled_at": "2023-04-15T03:00:00Z",
			"destination": {
                "geometry": {
                    "type": "Point",
                    "coordinates": [
                        -122.39704549527752,
                        47.66651089926278
                    ]
                },
                "address": "Ballard Locks",
                "radius": 50
            },
			"capacity_used": 1,
			"expected_service_time": 600,
			"type": "drop",
			"metadata": {
				"customer": "Ballard Locks"
			}
		},
        {
			"order_handle": "order-2023041313_04",
			"scheduled_after": "2023-04-15T01:00:00Z",
			"scheduled_at": "2023-04-15T03:00:00Z",
			"destination": {
                "geometry": {
                    "type": "Point",
                    "coordinates": [
                        -122.40777433051586,
                        47.67477596253224
                    ]
                },
                "address": "Rays Boathouse",
                "radius": 50
            },
			"capacity_used": 1,
			"expected_service_time": 600,
			"type": "drop",
			"metadata": {
				"customer": "Boat House"
			}
		}
	]
}

Key parameters that depend on your business requirements are:

plan_mode: this defines the mode in which planning is being done. scheduled mode is used for planning orders for the future based on driver schedules. Other available modes are pool, on-demand and manual.
ops_group_handle: is the Operations group for which the order is being planned. The planning will infer parameters like route starting location from the ops group settings
orders: array of orders for which the route is to be planned.

Planning orders is an async process here's a sample response to such a request:

{
    {
        "message": "Order Planning Initiated",
        "plan": {
            "id": "70d1bfb1-249d-4949-91c0-5d0303797341",
            "href": "/orders/plans/70d1bfb1-249d-4949-91c0-5d0303797341"
        }
    }
}

As you can see the response has a message indicating order planning is initiated. When planning is completed if you have setup webhooks you will receive a webhook for planning completion. Alternatively, you can use the href url to GET the request manually which is usually preferred in testing scenarios.

Here's a sample webhook received for when planning is completed. As you can see the webhook is for has a type:order with a value:order_planning_completed to indicate succesful order planning. In addition to summary information, the payload contains a route_handles_created object which provides the list of route handles created.

[
  {
    "account_id": "f00dda0f-bbbd-4dbb-911c-186ac45c150a",
    "type": "order",
    "data": {
      "value": "planning_completed",
      "ops_group_handle": "ops_group_STL",
      "num_orders": 2,
      "num_unplanned_orders": 0,
      "num_routes": 1,
      "planning_sequence_number": 1,
      "started_at": "2023-04-14T06:00:13.873Z",
      "completed_at": "2023-04-14T06:00:21.890Z",
      "route_handles_created": [
        "da9dfa53-3ea7-4377-83de-fb7d4c93d02d"
      ]
    },
    "version": "3.0.0",
    "created_at": "2023-04-14T06:00:21.890Z"
  }
]

4. Live order tracking

To start live tracking of orders in a route, you can use the route_handle provided in the previous step and call the Orders API. You can learn how to do that in the live order tracking guide.