Estimate order routes

Introduction

Logistics teams responsible for order fulfillment need to generate estimated order routes which include the sequence of orders, their ETAs 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. Note estimating routes only creates a route estimation for evaluation and does not start track them. To track an order route please refer to this guide.

Getting started

1. Setup Ops groups

Ops groups in HyperTrack represent the units around which your business operations are structured. For instance, if your business operates with stores, then each store may be its own operations group. For drivers to be eligble to fulfill an order, they must be part of the ops groups for which the order is being planned.

You can setup ops 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.

You can find detailed API references here.

2. Generating a Route estimate

After setting up your ops groups, the Orders API lets you generate a route estimate for a sequence of orders based on the Ops Group settings. Here's a sample payload to help you get started quickly:

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

{
    "ops_group_handle": "ops_group_test",
    "device_id":"00000000-BD4D-46A0-BED9-53BAF09A41B1",
    "orders": [
      {
        "order_handle": "order-000133",
        "scheduled_after": "2023-04-05T22:00:00Z",
        "scheduled_at": "2023-04-05T23:00:00Z",
        "destination": {
          "geometry": {
            "type": "Point",
            "coordinates": [-122.398096, 37.793038]
          },
          "address": "420 Montgomery Street, San Francisco, CA 94108, United States",
          "radius": 50
        },
        "product_type": ["plumber"],
        "capacity_used": 1,
        "expected_service_time": 800,
        "type": "drop",
        "metadata": {"customerId": "2233322"}
      },
      {
        "order_handle": "order-000144",
        "scheduled_after": "2023-04-05T23:00:00Z",
        "scheduled_at": "2023-04-05T23:30:00Z",
        "destination": {
          "geometry": {
            "type": "Point",
            "coordinates": [-122.398096, 37.793038]
          },
          "address": "425 Montgomery Street, San Francisco, CA 94108, United States",
          "radius": 50
        },
        "product_type": ["plumber"],
        "capacity_used": 1,
        "expected_service_time": 800,
        "type": "drop",
        "metadata": {"customerId": "2233321"}
      }
    ]
}

Key parameters that depend on your business requirements are:

• ops_group_handle: this identifies the Operations Group for the orders so the necessary setup parameters 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 array of orders for which the route is to be estimated. The route estimate will retiain the sequence of orders provided 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 acceptance.

3. Live order tracking

Once a route is accepted you can start tracking by calling the Orders API by referencing the route_handle provided in the route returned in the previous step. You can find the steps here.

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.