Track orders using Geotags

Introduction

Geotags help you tag the geolocation of work done by drivers on a timeline. As drivers move about performing actions in the app, the time and location of those actions get geotagged along with associated metadata.

When fulfilling an order, each geotag can be associated with an order_handle which is a unique identifier of an order in your business. This helps you roll up the geotags under an order which can be retrieved using our API or viewed through the dashboard. The geotag_type is a property that can be used to label the different segments in the order fulfillment process.

Let's consider an example. James is the driver in your fleet who needs to deliver a package to your customer. When the order is assigned to James, he can generate a geotag from his app with a unique order_handle (e.g first-order), and a geotag_type as assigned. When James arrives at the customer location, he could generate another geotag with the same order_handle and the geotag_type as arrived. Finally, once the order fulfillment is complete, he can generate another geotag with the geotag_type as completed. Using the APIs and dashboard views you can look at this order with its corresponding geotags. If you want to look at the segments in the order, then you could use the geotag_type to do this.

Geotags provides the ability to get true distance and duration travelled by your drivers on ground. Each geotag is enriched to provide the distance and duration from the previous geotag or the start of your driver's shift. This provides a way to aggregate these metrics across the driver or an order.

Geotags are also useful to track deviations from expected locations. When generating a geotag, the expected location can also be provided to compute the deviation and help you take action in real-time through application workflows. If we consider the above example, for the arrived and completed geotags, you can provide the customer location as the expected location to get the deviation information. This helps your operations track that things are happening at the right time and place as expected, and proactively improve when they don’t.

The figure below provides an overview of how the Geotags feature works and the guide walks you through how you can implement it:

Create Geotags

Use the geotags SDK method to tag the geolocation of actions in the driver's app. HyperTrack SDK provides Geotags on iOS and Android.

The order_handle and geotag_type can be passed as fields in the metadata and are used for grouping and aggregation of ground truth metrics. Any additional metadata can also be attached to the geotag to help better filter your data.

HyperTrack platform will process geotags sent from your mobile app in the cloud and process them in real-time with analysis for location accuracy.

🚧

Geotags are generated in the mobile app through the HyperTrack SDK. Your app is the source of truth for geotagging.

📘

If your driver's device is temporarily disconnected due to a network loss, geotags generated by your drivers will be captured offline and sent to HyperTrack once connection is restored.

Payload structure

Geotag payload (metadata) is a JSON object that enriches the geotag with relevant information.

In our example, if the driver James arrives at the customer location, the payload may look like the one below:

{
  "order_handle": "first-order",
  "geotag_type": "arrived",
  "item": "Office chair",
  "quantity": 1,
  "customer_name": "John Clive"
}

When you generate a geotag in your app, HyperTrack will process your geotag for location and provide you with accurate distance and duration metrics between the previous geotag (or from the start of your driver's shift) to this geotag.

Examples

The examples below show the sample code with the payload for the arrived geotag that James's app would send:

// create new geotag payload
Map<String,Object> payload = new HashMap<>();

// add event details from the example above

payload.put("order_handle": "first-order");
payload.put("geotag_type": "arrived");
payload.put("item": "Office chair");
payload.put("quantity": 1);
payload.put("customer_name": "John Clive");

sdkInstance.addGeotag(payload);

// create new geotag payload
Map<String,Object> payload = new HashMap<>();

// add event details from the example above

payload.put("order_handle": "first-order");
payload.put("geotag_type": "arrived");
payload.put("item": "Office chair");
payload.put("quantity": 1);
payload.put("customer_name": "John Clive");

sdkInstance.addGeotag(payload);

if let custom_event_marker = HyperTrack.Metadata(rawValue: [
  "order_handle": "first-order",
  "geotag_type": "arrived",
  "item": "Office chair",
  "quantity": 1,
  "customer_name": "John Clive"]) {
  hyperTrack.addGeotag(custom_event_marker)
} else {
  // custom_event_marker can't be represented in JSON
}

// add event details from the example above

NSDictionary *dictionary = @{@"order_handle": @"first-order",
                            @"geotag_type": @"arrived",
                            @"item": @"Office chair",
                            @"quantity": @1,
                            @"customer_name": @"John Clive"};

HTMetadata *custom_event_marker = [[HTMetadata alloc] initWithDictionary:dictionary];
if (custom_event_marker != nil) {
  [self.hyperTrack addGeotag:custom_event_marker];
} else {
  // custom_event_marker can't be represented in JSON
}

Using expected location for deviations

Optionally, you can specify an expected location longitude and latitude for a geotag.

This will allow HyperTrack to provide the deviation between actual and expected locations which you can use to measure address accuracy and driver behavior.

This computed deviation information will be available in the API, the Ops dashboard and the webhooks.

For example, if you want to know if the driver James arrived at the customer location to fulfill the order, you could use a payload similar to the one below:

// create new geotag payload
Map<String,Object> payload = new HashMap<>();

// add event details from the example above

payload.put("order_handle": "first-order");
payload.put("geotag_type": "arrived");
payload.put("item": "Office chair");
payload.put("quantity": 1);
payload.put("customer_name": "John Clive");

Location expectedLocation = new Location("any");
expectedLocation.setLatitude(35.0476912);
expectedLocation.setLongitude(-90.0260493);

sdkInstance.addGeotag(payload, expectedLocation);

// create new geotag payload
Map<String,Object> payload = new HashMap<>();

// add event details from the example above

payload.put("order_handle": "first-order");
payload.put("geotag_type": "arrived");
payload.put("item": "Office chair");
payload.put("quantity": 1);
payload.put("customer_name": "John Clive");

val expectedLocation = Location("any")
expectedLocation.longitude = -90.0260493
expectedLocation.latitude = 35.0476912

sdkInstance.addGeotag(payload, expectedLocation);

Consume Orders with Geotags

The HyperTrack ops view displays all the orders in the selected timerange with their respective geotags. This view is fully embeddable and can be integrated directly into your Ops dashboard.

This view gives your Ops teams a rich experience with geotags grouped and collapsed into the individual orders. Each row contains sufficient information about an order. On expanding the order, you can dive deeper into the metrics specific to each geotag that was part of the order. The filters provide the ability to slice information based on a timerange and the ops group.

The charts in the view provide counts and aggregates over the selected timerange to visualize fulfillment progress to help Ops teams ensure that things are progressing as expected.

Webhooks

If your app business workflow requires real-time integration with the driver actions on the field, you may use HyperTrack webhooks feature to get information as soon as the driver for instance generates a geotag in an order.

Please review an example payload shown below.

The webhook payload provides the data sent when the driver generated the geotag from the app. The order_handle and geotag_type help identify the order the geotag belongs to,the and segment it identifies. In addition, the location, distance in meters, duration in seconds, start_location from the previous geotag event for which distance and duration is generated, and the recorded_at timestamp are provided.

{
  "created_at": "2023-08-01T13:52:07Z",
  "recorded_at": "2023-08-01T13:52:08Z",
  "data": {
    "metadata": {
      "item": "Office chair",
      "quantity": 1,
      "customer_name": "John Clive"
    },
    "order_handle": "order-1",
    "geotag_type": "arrived",
    "distance": 238,
    "duration": 63,
    "driver_handle": "James",
    "location": {
      "type": "Point",
      "coordinates": [
              -6.2755,
              57.6398983
      ]
    },
  },
  "type": "geotag",
  "version": "3.0.0"
}