Estimate and dispatch order routes

Introduction

Businesses fulfilling customer orders need to generate order routes which include the sequence of orders to be fulfilled and the estimated route distance and duration. This provides visibility to drivers and operations teams on the work to be done. HyperTrack Orders API enables just that very easily.

This guide walks you through how you can generate estimated routes for a sequence of orders and dispatch them to drivers.

Getting started

1. Setup Operations Groups

Operations groups in HyperTrack API represent the units around which your business operations are structured. For instance, if your business operates with stores, then each store can be its own operations group.

You can setup Operations Groups via the Ops Groups APIs . Here's a sample payload to help you get started:

POST https://v3.api.hypertrack.com/ops-groups

{
   "ops_group_handle":"ops_group_test",
   "ops_group_label": "Store",
   "route_start_location": "ops_group_home",
   "route_completion_type": "end_at_last_order",
   "ops_group_home": {
    "geometry":{
       "coordinates":[
          -122.4275288309666,
          37.759384264709496
       ],
       "type":"Point"
    },
    "address":"Berkeley store address"
  }
}

Key setup parameters that depend on your business logic are:

ops_group_label: This represents the unit for which the ops group is defined like say a store or a warehouse.
ops_group_home: This represents where the ops group is located like the location of a store or a warehouse.
route_start_location: This represents how routes are started for that operations group. If routes are started from the warehouse, this should be set as ops_group_home. Alternatively, if a driver's live location should be used to start a route, then this should be set as live_location.
route_completion_type: This dictates how routes should be completed. For instance, if a driver needs to return to the starting location to complete the route this should be set as return_to_start_location. Alternatively if the last order is where the route completes, this should be set as end_at_last_order.

For detailed API references please refer to here.

2. Generating a Route estimate

After setting up your operations groups, this step lets you generate a route estimate for a sequence of orders your planning system may have decided. Use Orders API and here's a sample payload to help you get started quickly:

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

{
   "orders":[
      {
         "order_handle":"test_route_order_1",
         "destination":{
            "geometry":{
               "type":"Point",
               "coordinates":[
                  77.66627202172793,
                  12.91495667490461
               ]
            },
            "radius":30
         },
         "scheduled_at":"2022-10-06T14:40:00.000Z",
         "capacity_used":1,
         "expected_service_time":1200,
         "metadata":{
            "test_order":true,
            "store_name":"test_store"
         },
         "scheduled_after":"2022-10-06T14:20:00.000Z"
      },
      {
         "order_handle":"test_route_order_2",
         "destination":{
            "geometry":{
               "type":"Point",
               "coordinates":[
                  77.6829203937441,
                  12.91300652095342
               ]
            },
            "radius":30
         },
         "scheduled_at":"2022-10-06T15:30:00.000Z",
         "capacity_used":1,
         "expected_service_time":1200,
         "metadata":{
            "test_order":true,
            "store_name":"test_store"
         },
         "scheduled_after":"2022-10-06T15:00:00.000Z"
      },
      {
         "order_handle":"test_route_order_3",
         "destination":{
            "geometry":{
               "type":"Point",
               "coordinates":[
                  77.67085244162719,
                  12.919008170531209
               ]
            },
            "radius":30
         },
         "scheduled_at":"2022-10-06T16:40:00.000Z",
         "capacity_used":1,
         "expected_service_time":1200,
         "metadata":{
            "test_order":true,
            "store_name":"test_store"
         },
         "scheduled_after":"2022-10-06T16:15:00.000Z"
      }
   ],
   "route":{
      "metadata":{
         "store_name":"test_store"
      }
   },
   "device_id":"00000000-C3C6-4678-89B5-259BDE4A9C26",
   "ops_group_handle":"Bangalore_east",
   "intent":"self_improving"
}

Key parameters that depend on your business requirements are:

intent: this should be set as self_improving to indicate to HyperTrack that order is in the planning stage.
ops_group_handle: this identifies the ops_group for the orders so the necessary context can be referenced.
device_id: this is an optional parameter depending on the Ops Group setup. If the ops group uses ops_group_home as the route start location this parameter is not required. If the ops group uses live_location as the start location this parameter is required to indicate which drivers location we should use.
orders: this contains the orders in sequences whose route is to be estimated.

The route estimate will retain the sequence of orders in the request and will include the ETA for each order incorporating drive time and service time for each order. The route estimate will also include a route_handle and a version to identify the route that has been generated and its version.

After receiving the route estimate you can share it with your drivers or ops teams for review and acceptance as per your business requirements. Once a driver has accepted the route you can dispatch it as described below.

Detailed Orders API references are available here.

3. Live order tracking

The Orders API lets you easily dispatch routes to start live order tracking by making a request as shown below:

POST https://v3.api.hypertrack.com/orders/routes/<route_handle>/dispatch?version=<version>

This will start live order tracking which includes calclulating ETAs, generating shareable tracking links, and identifying risk factors for each order in the route as it is completed. For more details on live order tracking please refer to this guide.

4. High Level Technical workflow

The diagram below provides a high level step-by-step integration workflow for the Orders API:

Questions?

For questions or comments about orders view, please do not hesitate to contact us.

Introduction​

Getting started​

1. Setup Operations Groups​

2. Generating a Route estimate​

3. Live order tracking​

4. High Level Technical workflow​

Questions?​