Track orders using Routes

Introduction

The HyperTrack Orders API lets you track live orders with ETAs, delays, arrivals, risks and more through an API call.

Each route:

• Automatically starts driver tracking on the device when dispatched and stops tracking upon route completion
• Generates order completion markers that are used to generate distances traveled per order and deviations from destination
• Returns a mobile-friendly share URL per order for customers to get a real-time order tracking experience
• Returns a dashboard-friendly embed URL per route for ops managers to get a real-time route view

On-time routes versus flexible routes

Routes containing a fixed sequence of orders are created by passing in the "track_mode":"on_time" flag to the Orders API request.
On-time routes additionally provide:

• Estimated ETAs with live traffic conditions and re-routes
• Notifications about order delays and on time arrival scores when optional scheduled_at attribute is provided

In this sample of an embed URL for a route created with "track_mode":"on_time" flag, you can see the estimated route and arrival times.

And here is a screenshot of the corresponding mobile-friendly share url:

For orders that are fulfilled in a flexible sequence and do not require ETAs, create routes with
"track_mode":"flex" flag.
Flexible routes give you the same mobile-friendly share URL per order for customers and dashboard-friendly embed URL for ops managers, but don't create ETAs or delay notifications.
For flexible routes, the optional "scheduled_at" parameter is not relevant as the orders can be completed in any sequence.

Here is the same route as above, but created with the "track_mode":"flex" flag. As you can see, there is no estimated arrival time nor any estimated routes.

And here is a screenshot of the mobile friendly share url for the same route. There are no ETAs nor estimated routes shared.

Order data is used to generate insights on route efficiency, on-time arrival, completion at destination, and time spent at destination. Past routes may be replayed for non-repudiation in case of escalations or other exceptions.

📘

To automatically start order tracking you must integrate silent push notifications for iOS and Android. The device will stop tracking when all active routes for device are completed. HyperTrack uses a combination of silent push notifications and sync method on the SDK to ensure that tracking starts and stops on the device as expected.

Tracking Orders on HyperTrack

To track orders on HyperTrack you can either start with an array of orders OR if you have already planned a route on HyperTrack and have a route_handle you can directly reference that as described here.

Tracking using a sequence of orders:

To create and track a route starting with an array of orders, you must define a payload structured as follows:

{
  "device_id": "00000000-C3C6-4678-89B5-259BDE4A9C26",
	"track_mode": "on_time",
	"orders": [{
			"order_handle": "test-order-01",
			"scheduled_after": "2023-03-22T22:00:00Z",
			"scheduled_at": "2023-03-22T23:00:00Z",
			"destination": {
				"geometry": {
					"type": "Point",
					"coordinates": [74.24219516188421, 16.693551259417756]
				},
				"address": "Lucky Bazar",
				"radius": 50
			},
			"expected_service_time": 800
		},
		...
		]
}

Parameter expected_service_time specifies time in seconds that driver expects to service an order. Note that order_handle must be a unique identifier for your order, while destination is required and scheduled_at and expected_service_time parameters are optional.

Please see code examples below:

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

payload='{
  "device_id": "00000000-BD4D-46A0-BED9-53BAF09A41B1",
  "track_mode": "on_time",
  "orders": [
    {
      "order_handle": "order-00001",
      "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-00002",
      "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"}
    }
  ]
}'

curl --location 'https://v3.api.hypertrack.com/orders' \
--user "account_id:secret_key"  \
--header 'Content-Type: application/json' \
--data $payload

var request = require('request');


let AccountId = 'account_id';
let SecretKey = 'secret_key';
let AUTHORIZATION_TOKEN = btoa(`${AccountId}:${SecretKey}`);

console.log(AUTHORIZATION_TOKEN)

  body: JSON.stringify({
  "device_id": "00000000-BD4D-46A0-BED9-53BAF09A41B1",
  "track_mode": "on_time",
  "orders": [
    {
      "order_handle": "order-00001",
      "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-00002",
      "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"}
    }
  ]
})

};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

import requests
import json
import base64

url = "https://v3.api.hypertrack.com/orders/track"

AUTHORIZATION_TOKEN = "Basic {}".format(
    base64.b64encode(f"{account_id}:{secret_key}".encode("utf-8")).decode("utf-8")
)

headers = {“Content-Type”: “application/json”,
            “Authorization”: AUTHORIZATION_TOKEN}


route_data = {
  "device_id": "00000000-BD4D-46A0-BED9-53BAF09A41B1",
  "track_mode": "on_time",
  "orders": [
    {
      "order_handle": "order-00001",
      "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-00002",
      "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"}
    }
  ]
}

response = requests.request("POST", url, headers=headers, data=route_data)

print(response.text)

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");

RequestBody body = RequestBody.create(mediaType, "{\n  \"device_id\": \"00000000-BD4D-46A0-BED9-53BAF09A41B1\",\n  \"track_mode\": \"on_time\",\n  \"orders\": [\n    {\n      \"order_handle\": \"order-00001\",\n      \"scheduled_after\": \"2023-04-05T22:00:00Z\",\n      \"scheduled_at\": \"2023-04-05T23:00:00Z\",\n      \"destination\": {\n        \"geometry\": {\n          \"type\": \"Point\",\n          \"coordinates\": [-122.398096, 37.793038]\n        },\n        \"address\": \"420 Montgomery Street, San Francisco, CA 94108, United States\",\n        \"radius\": 50\n      },\n      \"product_type\": [\"plumber\"],\n      \"capacity_used\": 1,\n      \"expected_service_time\": 800,\n      \"type\": \"drop\",\n      \"metadata\": {\"customerId\": \"2233322\"}\n    },\n    {\n      \"order_handle\": \"order-00002\",\n      \"scheduled_after\": \"2023-04-05T23:00:00Z\",\n      \"scheduled_at\": \"2023-04-05T23:30:00Z\",\n      \"destination\": {\n        \"geometry\": {\n          \"type\": \"Point\",\n          \"coordinates\": [-122.398096, 37.793038]\n        },\n        \"address\": \"425 Montgomery Street, San Francisco, CA 94108, United States\",\n        \"radius\": 50\n      },\n      \"product_type\": [\"plumber\"],\n      \"capacity_used\": 1,\n      \"expected_service_time\": 800,\n      \"type\": \"drop\",\n      \"metadata\": {\"customerId\": \"2233321\"}\n    }\n  ]\n}");

String authString = "Basic " +
  Base64.getEncoder().encodeToString(
    String.format("%s:%s", "account_id_value","secret_key_value")
      .getBytes()
  );

Request request = new Request.Builder()
  .url("https://v3.api.hypertrack.com/orders/")
  .post(body)
  .addHeader("Authorization", authString)
  .build();

Response response = client.newCall(request).execute();

System.out.println(response.body().string());

Tracking using a route_handle:

To start tracking a route using a route_handle provided by HyperTrack, you can make a POST request with the payload as described below:

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

{
   "track_mode": "on_time",
   "route_handle": "277455c2-7d01-4d9e-bdbd-55dde53e139f"
}

📘

Location coordinates in GeoJSON object are called geometry with a Point that represents the location coordinates. Location coordinates require longitude before latitude. To change the default radius, you can pass a radius property (integer in meters) to the destination object.

Share Order tracking views with customers

Orders API returns a share_url for each customer's order destination upon successful creation of the route.

The share_url is built for sharing with customers. While the route is ongoing, customers will see a mobile-web view of the order's live location with route and ETA to the order destination.

For completed orders, customers will see the route summary from starting location to the order destination.

Share URL has the following structure: https://trck.at/{7_digit_tracking_id}.

This makes it a total of 23 characters, and therefore a friendly URL to share via text or other messengers. Share URLs stay accessible permanently and show order summary after order completion.

Live data for routes is available for native tracking experiences through callbacks in iOS and Android SDKs. You can also use GraphQL API to stream live data for routes as well.

Customize tracking view

HyperTrack offers you options that allow you to create customizations for share URLs with ETA for your customers.

Customize with url query parameters

The share URL experience can be modified with the following query parameters appended to it:

• layer
• mini
• icon
• map_only
• destination_icon
• show_pickup
• pickup_icon

Layer query parameter

This parameter offers you options to customize map layer used to render the share URL experience. The layer parameter can have the following values:

• base - default choice for the share URL
• street - additional street detail is shown in the map
• satellite - satellite view is used as shown in an example below

For example:

https://trck.at/abcdexyz?layer=street

To illustrate, please review corresponding images below for each of the layer option value usage.

Icon query parameter

This parameter offers you options to customize how your tracked device appears on the map. The icon parameter can have the following values:

• car
• bike
• bus

https://trck.at/abcdexyz?icon=car

Mini query parameter

• mini - this parameter allows to hide route details used to show in the map as shown below.

https://trck.at/abcdexyz?mini=true

https://trck.at/abcdexyz?mini=all

Map_only query parameter

• map_only - this parameter can be used to hide the route card shown on the map.

https://trck.at/abcdexyz?map_only=true

Destination_icon query parameter

• destination_icon - this parameter can be used to show a custom icon for the destination on the map.

https://trck.at/abcdexyz?destination_icon=<URL to public SVG image>

Show_pickup query parameter

• show_pickup - this parameter can be used to show the pickup location on the map.

https://trck.at/abcdexyz?show_pickup=true

Pickup_icon query parameter

• pickup_icon - this parameter can be used to show a custom icon for the pickup location on the map.

https://trck.at/abcdexyz?pickup_icon=<URL to public SVG image>

Customize with reserved route metadata keys

In order to perform such customizations, you may use these reserved route metadata keys to help define public share URL experience. Use Orders API with these reserved metadata keys when creating a route.

• ht_view_text_ongoing - defines a title of an ongoing delivery, for example, "Your order for xyz is on the way!"
• ht_view_text_completed - defines a title for a delivery that was completed, for example, "Your order for xyz is delivered!”
• ht_view_href_completed - provides an option to the customer to go back to the link which exposes order details in your delivery app
• ht_view_href_text_completed - once this option is used, your completed route will have a title defined by the value of this key
• ht_view_hide_summary_completed - this option allows you to remove completed route summary from the view which is included by default

Embed Route views in ops dashboards

Orders API returns embed_url upon successful creation of the route.

The embed_url is built for embedding in ops dashboards. While the route is ongoing, ops dashboard users will see a desktop-web view of the route's timeline, live location, arrival status, estimated route and ETA to destination.

For completed routes, dashboard will see the route summary with a detailed timeline from start to complete.

While shareable views are accessible to everyone with the URL, embed views includes your publishable key. Although the permalink of each URL in the dashboard includes the publishable key, your publishable key is available in the Setup page of your dashboard.

The embed URL format is https://embed.hypertrack.com/trips/{route_handle}?publishable_key={publishable_key}

📘

To identify a HyperTrack Route with your application order, and destination with your order location, please use the metadata object for route and destination respectively.

Inline frames

Please see how to use inline frames to create embeddable operations dashboards.

Hide route completion button

This parameter offers you option to hide route completion button. Route completion button is shown by default. The icon parameter can have the following value:

• false

https://embed.hypertrack.com/trips/{route_handle}?publishable_key={publishable_key}&trip_complete=false

Get Order routes, estimates and views

Once the route is created successfully, the Orders API responds with an active route object that returns the original payload with additional properties and the route starts tracking immediately.

Additional properties include an estimate with route and ETA for each order destination, mobile-friendly share_url for each order customer. Use desktop-friendly embed_url inside views object for ops dashboards to view the entire route status in real-time.

The order destination object in the response will now contain address field which is an address that is reverse geocoded from the order destination coordinates submitted in the route creation request. You can use this address to show the order destination to the driver after creating the route.

{
	"route_handle": "d221b115-7974-4c13-af6f-c284479d1420",
	"status": "dispatched",
	"version": 1,
	"embed_url": "https://embed.hypertrack.com/trips/d221b115",
	"orders": [{
			"order_handle": "test-order-01",
			"fulfillment_attempt": 0,
			"status": "ongoing",
			"destination": {
				"geometry": {
					"type": "Point",
					"coordinates": [
						74.24219516188421,
						16.693551259417756
					]
				},
				"address": "Lucky Bazar",
				"radius": 50
			},
			"intent": "on_time",
			"scheduled_after": "2023-03-22T22:00:00.000Z",
			"scheduled_at": "2023-03-22T23:00:00.000Z",
			"started_at": "2023-03-21T11:19:42.331Z",
			"expected_service_time": 800,
			"capacity_used": 1,
			"region": {
				"city": "Kolhapur",
				"country": "India",
				"state": "Maharashtra",
				"geohash": "tduycqvw",
				"postcode": "416001"
			},
			"share_url": "https://trck.at/WqeWQKZZnb",
			"device_id": "00000000-C3C6-4678-89B5-259BDE4A9C26",
			"created_at": "2023-03-21T11:19:40.525Z",
			"assigned_at": "2023-03-21T11:19:40.833Z"
		},
		{
			"order_handle": "test-order-02",
			"fulfillment_attempt": 0,
			"status": "ongoing",
			"destination": {
				"geometry": {
					"type": "Point",
					"coordinates": [
						74.251713861659,
						16.701598798641058
					]
				},
				"address": "Star Bazar",
				"radius": 50
			},
			"intent": "on_time",
			"scheduled_after": "2023-03-22T22:00:00.000Z",
			"scheduled_at": "2023-03-22T23:00:00.000Z",
			"started_at": "2023-03-21T11:19:42.403Z",
			"expected_service_time": 800,
			"capacity_used": 1,
			"region": {
				"city": "Kolhapur",
				"country": "India",
				"state": "Maharashtra",
				"geohash": "tduz18km",
				"road": "Old Pune Bengaluru Highway",
				"postcode": "416003"
			},
			"share_url": "https://trck.at/PnNJQOM2n1",
			"device_id": "00000000-C3C6-4678-89B5-259BDE4A9C26",
			"created_at": "2023-03-21T11:19:40.525Z",
			"assigned_at": "2023-03-21T11:19:40.833Z"
		},
		{
			"order_handle": "test-order-03",
			"fulfillment_attempt": 0,
			"status": "ongoing",
			"destination": {
				"geometry": {
					"type": "Point",
					"coordinates": [
						74.25630448977986,
						16.69639826011762
					]
				},
				"address": "CSD Canteen",
				"radius": 50
			},
			"intent": "on_time",
			"scheduled_after": "2023-03-22T22:00:00.000Z",
			"scheduled_at": "2023-03-22T23:00:00.000Z",
			"started_at": "2023-03-21T11:19:42.527Z",
			"expected_service_time": 800,
			"capacity_used": 1,
			"region": {
				"city": "Kolhapur",
				"country": "India",
				"state": "Maharashtra",
				"geohash": "tduycxrz",
				"road": "Old Pune Bengaluru Highway",
				"postcode": "416004"
			},
			"share_url": "https://trck.at/jpdbQjZPvy",
			"device_id": "00000000-C3C6-4678-89B5-259BDE4A9C26",
			"created_at": "2023-03-21T11:19:40.526Z",
			"assigned_at": "2023-03-21T11:19:40.833Z"
		}
	],
	"estimate": {
		"start_by": "2023-03-22T22:27:49.000Z",
		"distance": 3544,
		"duration": 332,
		"start_location": {
			"type": "Point",
			"coordinates": [
				74.24219516188421,
				16.693551259417756
			],...
		},
		"end_location": {
			"type": "Point",
			"coordinates": [
				74.25630448977986,
				16.69639826011762
			]
		},
		"polyline": {
			"type": "LineString",
			"coordinates": [
				[
					74.24228,
					16.69357
				]
			]
		}
	},
	"started_at": "2023-03-21T11:19:41.600Z",
	"assigned_at": "2023-03-21T11:19:40.662Z",
	"created_at": "2023-03-21T11:19:40.812Z",
	"device_id": "00000000-C3C6-4678-89B5-259BDE4A9C26",
	"region": {
		"city": "Kolhapur",
		"country": "India",
		"state": "Maharashtra",
		"geohash": "tduycqvw",
		"postcode": "416001"
	}
}

Route Object will have an estimate object which contains:

• distance estimated route distance (in meters)
• duration estimate route duration (in meters)
• start_location first point (in GeoJSON format) on route
• end_location last point (in GeoJSON format) on route
• polyline contains an array of coordinates for the estimated route from the live location to the route completion point as polyline in GeoJSON LineString format. It is an array of Point coordinates with each element linked to the next, thus creating a pathway to the destination.

In order to get estimates for Orders, Orders API provides ability to Get Order Detail.

For each order, estimate object contains:

• arrive_at shows estimated time of arrival (ETA) as UTC timestamp
• distance shares estimated route distance (in meters)
• duration share remaining durations (in seconds)
• start_location first point (in GeoJSON format) on route
• end_location order destination location (in GeoJSON format)
• polyline contains an array of coordinates for the estimated route from the live location to the destination as polyline in GeoJSON LineString format. It is an array of Point coordinates with each element linked to the next, thus creating a pathway to the destination.

:::important
If the driver on the route is detected to be more than four hours away from the order destination, the estimate object is returned empty in the response.
:::

Track Order delays and no-shows

For orders with time slot or end time commitments, it is important to proactively manage delays and potential no-shows. Delays might trigger an automatic workflow, notify operations managers or reset customer expectations.

Use scheduled_at property in ISO8601 format to the order destination to indicate a scheduled arrival. Use this when the order has a time commitment to the customer. When set, HyperTrack will send order delay webhooks when the driver is highly likely to miss that time commitment.

With scheduled_at, operations pre-emptively act on delays and catch potential no-shows before they escalate.

Here are five examples of delays with actionable reasons.

Driver is delayed on the way to order destination

Delay is likely when the estimated route and ETA with live traffic conditions suggests a delay past scheduled time of arrival. Delays are notified over webhooks.

Delays are also flagged in ops views for each driver, order, and entire fleet, so ops managers can keep an eye on delays and take corrective action.

Customer support can replay routes to confirm customer and driver claims when escalations happen. Replays enable non-repudiation because these views can be shared as links with either party as needed.

Driver is moving away from destination

This example of a no-show is likely when the estimated route distance and ETA to destination keeps increasing despite movement, and the driver seems to have no intention to get to the order destination. In the example above, the green square on the right indicates the destination. The driver is moving, though not toward the destination. ETA becomes irrelevant.

There is the occasional issue with incorrect customer addresses, or a higher priority task that needed to be fulfilled before heading to the destination. In such scenarios, being aware of the driver's intent on the way is useful to proactively address a potential escalation.

Driver is delayed and stationary

HyperTrack uses activity transitions to infer that the driver is stationary, or driving, or walking. No-show is likely when the driver is stationary at a place and the order is running delayed beyond schedule time of arrival. The delay webhook includes activity so you may take corrective action for this specific scenario, such as sending a text message or notification to the driver, or re-assigning the order.

Activity transition data provided by the phone OS is noisy. HyperTrack makes it more accurate with additional processing. This way, you can rely on this data to take action. For instance, benign stops at a traffic light are eliminated while stops at places are retained.

Driver disables location permission

HyperTrack detects changes in driver device and app level permissions to infer driver's intent to be tracked while fulfilling an order. No-show is quite likely when the driver denies location permission after order assignment or while on the way.

Drivers often mention excessive battery drain and data usage as reasons to turn off permission. However, for most Android and iOS devices, the additional battery and data usage due to background location tracking is marginal. Custom ROMs and old devices might have higher battery impact. In general, HyperTrack data suggests high correlation between denied permissions and low productivity.

Driver becomes untrackable on the way

Device health and battery status is used to infer driver becoming un-trackable while the driver is on the route. In this example, the driver's battery went in the red and subsequently, the driver went off the radar.

When the phone is charging again, and the driver opens the app to re-connect with services, HyperTrack captures these events and syncs up the batched locations when available. This helps operations get the extra visibility around what might have happened during the outage.

Get Order status and Route summary

In your business workflow, you may need to take actions depending on the status of the route you created for your driver. HyperTrack provides real-time updates for your app via webhooks that deliver to you important events associated with your route.

Get status on webhooks

Actions performed by the driver with an order results in a webhook notification to your configured end point. Please refer to this guide section for more information. You can use the order status update notifications to add logic to your business workflows.

📘

Whenever you use scheduled_at for an order in the route, you will get delay notifications webhooks whenever HyperTrack detects that delivery driver is not able to deliver a given order by scheduled time.

It is up to you to decide how to utilize route updates. To give you an idea, the following can be done:

• complete routes based on custom logic
• update database records of orders
• send mobile device notifications
• update real-time views and maps
• start custom processes (training of AI models, send custom emails, etc)
• get the distance traveled during the route as soon as it's completed as part of the webhook payload

Get summary from API

Get Orders API

GET Orders APIs to retrieve active and completed route data.

For all active and completed routes, a summary object is returned as part of the route response payload. If routes is still in active state, the summary object will contain the latest from the driver's device.

GET   https://v3.api.hypertrack.com/orders/routes/{route_handle}

Additionally, you can get route data for multiple actively tracked routes.

GET   https://v3.api.hypertrack.com/orders/routes

You can set the status path parameter to completed to get past routes.

Route Detail payload

Route Detail includes route_handle & device ID, start and completion timestamps, share views for each order & entire route embed views, and summary related information.

Summary information includes start & complete location, duration, distance, polyline (location timeseries GeoJSON), and markers. Markers include activities, outages and order destination arrivals & exits.

A sample route Detail information is shared below.

To understand the route response payload data in full, please visit this reference documentation section.

{
	"route_handle": "0c41eb41-a0e3-4f66-9952-4492e9cae3d2",
	"status": "completed",
	"version": 1,
	"embed_url": "https://embed.hypertrack.com/trips/0c41eb41",
	"orders": [{
		"order_handle": "order-11",
		"fulfillment_attempt": 0,
		"status": "completed",
		"destination": {
			"geometry": {
				"type": "Point",
				"coordinates": [
					74.24219516188421,
					16.693551259417756
				]
			},
			"address": "Lucky Bazar",
			"radius": 50
		},
		"intent": "on_time",
		"scheduled_after": "2023-03-22T22:00:00.000Z",
		"scheduled_at": "2023-03-22T23:00:00.000Z",
		"started_at": "2023-03-21T11:16:04.263Z",
		"expected_service_time": 800,
		"capacity_used": 1,
		"region": {
			"city": "Kolhapur",
			"country": "India",
			"state": "Maharashtra",
			"geohash": "tduycqvw",
			"postcode": "416001"
		},
		"share_url": "https://trck.at/jqJzQeJ1qb",
		"completed_at": "2023-03-21T16:42:28.468Z",
		"device_id": "00000000-C3C6-4678-89B5-259BDE4A9C26",
		"created_at": "2023-03-21T11:16:02.172Z",
		"assigned_at": "2023-03-21T11:16:02.401Z"
	}],
	"started_at": "2023-03-21T11:16:03.115Z",
	"assigned_at": "2023-03-21T11:16:02.319Z",
	"created_at": "2023-03-21T11:16:02.384Z",
	"device_id": "00000000-C3C6-4678-89B5-259BDE4A9C26",
	"region": {
		"city": "Kolhapur",
		"country": "India",
		"state": "Maharashtra",
		"geohash": "tduycqvw",
		"postcode": "416001"
	},
	"completed_at": "2023-03-21T16:42:28.468Z",
	"distance": 35484,
	"duration": 7493,
	"start_location": {
		"type": "Point",
		"coordinates": [74.23696625133121, 16.697283676261836]
	},
	"end_location": {
		"type": "Point",
		"coordinates": [74.24219516188421, 16.693551259417756]
	},
	"polyline": {
		"type": "LineString",
		"coordinates": [
			[74.24219516188421, 16.693551259417756, 30, "2021-02-18T15:12:00.000Z"],
			...
		]
	},
	"tracking_rate": 0.93,
	"markers": [
			{
		  	},...
		  ]

}

Manage Orders and Routes

You can perform the following operations with Orders API:

Complete or Cancel Order

Complete or Cancel an order inside an ongoing route. Once the order is canceled, it is permanently removed from the route, a new route is planned, and ETAs are updated. Orders are either completed or canceled by drivers in the app, or by other users in other business applications. Occassionally, you might complete orders based on arrival or exit at order destination. It is recommended to use this as a fallback mechanism only. Drivers may be driving through order destinations before returning to fulfill the order, or never reach destination

Update or Add Order

Update existing orders or Add another order to the existing route. Use the update method whenever you need to modify order attributes such as destination, scheduled_at or metadata. Use the add method to add another order to the sequence of orders in a route. This will modify the routes and ETAs of pending orders.

Snooze or Re-Add Order

Snooze or Re-add orders when the customer is unavailable and there is a need to change things ad-hoc. Snoozing an order disables it while re-adding the order enables it back to be included in the route. The driver's route and ETA are updated accordingly.

Change Order sequence

Re-sequence orders inside the route to reorder previously given orders. For example, an operations manager may discover an urgent need to raise delivery priority for a given customer and thus trigger a route change for the delivery driver.

Complete Route

Complete route once all orders in the route are completed or canceled. If you have orders in the route that have not yet been completed, this API call will automatically cancel all outstanding orders for you.

📘

Either way, please remember to complete your route!

Otherwise, HyperTrack will complete your route automatically after 24 hours if it is still active and send you a notification.

If the driver's device had automatically started tracking through Orders API, completing the route will automatically stop tracking the driver's device.

📘

Automatically stopping tracking on the device upon route completion requires you to integrate silent push notifications on iOS and Android.

While managing Orders and Routes, please account for the following use cases:

• Use arrival and exit notifications with caution. Drivers may be passing through order destination to look for parking or fulfilling another order before returning
• Completing the order upon arrival or at the destination will stop exit notifications for that order destination
• Some visits or gigs might require tracking multiple visits (arrivals and exits) to the destination
• Order completion marker helps compute deviation from destination and can be an important input to driver behavior or address accuracy
• On-demand orders involving pick and delivery might require dispatch to Nearby drivers already on a route, followed by adding orders to the route.

4. High Level Technical workflow

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

Questions?

Please do not hesitate to contact us at [email protected] with your questions and feedback.