TripV2 to Order API
Why Migrate to Orders API?
As shift work evolves, it's crucial for our customers to adapt to these changes. That’s why we've developed the new Orders API.
Previously, our Trips v2 API enabled customers to support use cases involving workers on multiple shifts per day by introducing the concept of Orders. We've taken this functionality a step further with the Orders API, offering more granular control and supporting advanced shift-based workflows. This shift from mere tracking to comprehensive location intelligence represents a holistic approach to understanding and addressing proof of work.
Here are some key features of the Orders API:
- A new range of APIs that provide more granular control for advanced workflows.
- Seamless integration with other HyperTrack features, such as Places, Geotags, and Visits.
- The introduction of the Places API, which leverages places of interest created through the Orders API to refine geofence definitions and provide insights based on historical visits. This enhancement ensures a more reliable proof of work and leads to better route optimizations. You can use the same Place API handle in Orders API calls while benefiting from ongoing updates and enhancements as HyperTrack refines geofence definitions for these places.
- The Orders suite now includes Clock-in/Clock-out signals to clearly define shift boundaries, aiding in better payout accuracy and dispute resolution.
- The performance of the API has been improved.
- Enhanced performance and geofence detection accuracy through the integration of the Orders/Places Suite with our new SDK, which delivers a more accurate location stream.
- Addition of more detailed information to our Webhooks.
These enhancements make the Orders API a robust tool for managing workforce logistics with precision and insight.
Migration Steps
1. Migrate from Devices to Workers
For the Orders API, we've introduced the concept of a Worker. This is the person that is assigned a gig and goes to your customer location to complete the perform the service. A worker is associated with only one device at any given instance, but we now provide the ability for the worker to change their device seamlessly between shifts while ensuring their work is correctly attributed to them.
To learn more on how to set up your workers check out our Worker Setup guide.
In this step, you can create a worker for each device you currently have in the HyperTrack system and map them.
2. Migrate your API from Trips to Orders
With the TripsV2 APIs, you used the following endpoints:
- POST /trips
- POST /trips/{trip_id}/complete
- GET /trips/{trip_id}
- GET /trips/{trip_id}/analytics
- GET /trips
Now we provide a larger set of APIs to support more granular workflows. To learn more about the available APIs check the Orders API Reference.
Here are some samples of the key API mappings:
a. Create Trip -> Orders
// POST /trips
{
"device_id": "65893616-AC7E-4740-AFB0-C42242FF9661",
"orders": [
{
"order_id": "test_order",
"metadata": {
"shift_id": "ccWZY7p",
"worker_id": "53332",
"business_name": "Eldon Roark Tennis Center",
"business_id": "Bsw2AJo",
"worker_name": "cyntresia d.",
"message": "cyntresia d. to Eldon Roark Tennis Center (ccWZY7p)"
},
"scheduled_at": "2024-02-26T01:30:00+00:00",
"destination": {
"radius": 500,
"geometry": {
"type": "Polygon",
"coordinates": [
[
[-90.013951, 35.031187],
[-90.013919, 35.030037],
[-90.012792, 35.030037],
[-90.012878, 35.031187],
[-90.013951, 35.031187],
[-90.013951, 35.031187],
[-90.013951, 35.031187],
[-90.013951, 35.031187],
[-90.013951, 35.031187]
]
]
}
}
}
]
}
With the new Orders API, you can use a previously created place via its place_handle value to create an order destination. See Places API guide on how to create a place required for this Orders API example below.
// POST /orders/track
{
"driver_handle": "[email protected]",
"track_mode": "on_time",
"orders": [
{
"order_handle": "test_order",
"destination": {
"place_handle": "eldon_roark_tennis_center"
},
"scheduled_at": "2024-02-26T01:30:00+00:00",
"metadata": {
"shift_id": "ccWZY7p",
"worker_id": "53332",
"business_name": "Eldon Roark Tennis Center",
"business_id": "Bsw2AJo",
"worker_name": "cyntresia d.",
"message": "cyntresia d. to Eldon Roark Tennis Center (ccWZY7p)"
}
}
]
}
b. Get trips -> orders
i. Fetch all trips -> all orders (GET /trips -> GET /orders)
// GET /trips
{
"data": [
{
"trip_id": "335f0424-4987-427f-abe1-f9bd5764bb11",
"started_at": "2024-09-19T14:30:17.057Z",
"completed_at": "2024-09-19T17:10:36.583Z",
"status": "completed",
"device_id": "5F9C5400-5732-4A02-B3DC-A5E06EE29901",
"views": {
"embed_url": "https://embed.hypertrack.com/trips/335f0424-4987-427f-abe1-f9bd5764bb11?publishable_key=Fw53422gv4apk5CaDU20cZizAAvj0tRJKlVvi3YAt3LshVq443PPgaf_KwkdWq_vS_b3W0o1",
"share_url": "https://trck.at/5qsJtpV1dj"
},
"metadata": {
"name": "James Smith",
"worker_type": "shift",
"shift": "shift-1",
"worker_id": "worker-1"
},
"departure": {
"geometry": {
"coordinates": [
-98.523552,
29.419194,
180.3
],
"type": "Point"
},
"address": "Guadalupe Street, Avenida Guadalupe, San Antonio, Bexar County, Texas, 78207, United States"
},
"orders": [
{
"order_id": "order-1",
"metadata": {
"name": "James Smith",
"worker_type": "shift",
"shift": "shift-1",
"worker_id": "[email protected]"
},
"scheduled_at": "2024-09-19T16:30:00.000Z",
"device_id": "5F9C5400-5732-4A02-B3DC-A5E06EE29901",
"completed_at": "2024-09-19T17:10:36.583Z",
"destination": {
"address": "5500 Mid Cities Parkway, Schertz, TX 78154",
"geometry": {
"type": "Point",
"coordinates": [
-98.2858361,
29.5979442
]
},
"radius": 450
},
"arrived_at": "2024-09-19T16:16:13.059Z",
"share_url": "https://trck.at/2Fs4tTy3da",
"status": "completed",
"departure": {
"address": "Guadalupe Street, Avenida Guadalupe, San Antonio, Bexar County, Texas, 78207, United States",
"geometry": {
"coordinates": [
-98.523552,
29.419194,
180.3
],
"type": "Point"
}
},
"duration_at_destination": 3264.0,
"started_at": "2024-09-19T14:30:17.057Z",
"service_time": 0,
"delayed": true,
"arrived": true,
"tracked": true,
"delayed_time": 85573,
"on_time": true,
"completed_at_destination": true,
"capacity": 1,
"end_address": "Mid-Cities Parkway, Schertz, Guadalupe County, Texas, 78154, United States",
"end_location": {
"type": "Point",
"coordinates": [
-98.285672,
29.59711
]
},
"assignment": "on_demand",
"deviation": 94,
"timezone": "America/Chicago",
"driver_handle": "[email protected]"
}
],
"destination": {
"destination_id": "order-1",
"trip_id": "335f0424-4987-427f-abe1-f9bd5764bb11",
"geofence_id": "840674d5-959e-4823-a249-f6aa54bc408a",
"delayed": true,
"arrived": true,
"arrived_at": "2024-09-19T16:16:13.059Z",
"exited_at": "2024-09-19T17:10:37.148Z",
"scheduled_at": "2024-09-19T16:30:00.000Z",
"address": "5500 Mid Cities Parkway, Schertz, TX 78154",
"geometry": {
"type": "Point",
"coordinates": [
-98.2858361,
29.5979442
]
},
"share_url": "https://trck.at/2Fs4tTy3da",
"metadata": {
"name": "James Smith",
"worker_type": "shift",
"shift": "shift-1",
"worker_id": "[email protected]"
},
"estimate": {
"number_of_reroutes": 22,
"number_of_traffic_refreshes": 10,
"traffic_time_per_meter": 0,
"route": {
"distance": 12000,
"duration": 3600,
"updated_at": "2024-09-19T16:21:27.438Z",
"last_sent_duration": 7,
"latest_processed_step_index": 15,
"latest_processed_waypoint_index": 0,
"remaining_distance": 4,
"remaining_duration": 7,
"polyline": {
"type": "LineString",
"coordinates": [
[
-98.28582,
29.59683
],
[
-98.28563,
29.59693
],
[
-98.28563,
29.59693
],
[
-98.28619,
29.59777
],
[
-98.28619,
29.59777
]
]
}
},
"arrive_at": "2024-09-19T18:02:52.846Z"
},
"radius": 450,
"capacity": 1,
"end_address": "Mid-Cities Parkway, Schertz, Guadalupe County, Texas, 78154, United States",
"end_location": {
"type": "Point",
"coordinates": [
-98.285672,
29.59711
]
},
"device_id": "5F9C5400-5732-4A02-B3DC-A5E06EE29901",
"duration_at_destination": 3264.0
},
"capacity": 10,
"optimise_route": false,
"flexible_route": false,
"vehicle_type": "car",
"timezone": "America/Chicago"
}
],
"pagination_token": "___eyJhY2NvdW50X2lkFs44w0kNzhkLWNkZGItNDQ2NS05ZjJhLTAyMTdjZTk4NmM0MyIsICJ0cmlwX2lkIjogImE0ZTdlZDE4LWNhYTMtNDRhOS1hNTA2LWM4NWIyKWWEm036882ICJzdGFydGVkX2F0IjogIjIwMjQtMDktMTlUMTQ6MzFqoSSQ12CCD",
"links": {
"next": "https://v3.api.hypertrack.com/trips/?pagination_token=___eyJhY2NvdW50X2lkFs44w0kNzhkLWNkZGItNDQ2NS05ZjJhLTAyMTdjZTk4NmM0MyIsICJ0cmlwX2lkIjogImE0ZTdlZDE4LWNhYTMtNDRhOS1hNTA2LWM4NWIyKWWEm036882ICJzdGFydGVkX2F0IjogIjIwMjQtMDktMTlUMTQ6MzFqoSSQ12CCD"
}
}
// GET /orders
{
"orders": [
{
"arrived_at": "2024-09-19T16:16:13.059Z",
"assigned_at": "2024-09-19T14:30:17.058Z",
"capacity_used": 1,
"completed_at": "2024-09-19T17:10:36.583Z",
"created_at": "2024-09-19T14:30:17.057Z",
"destination": {
"address": "5500 Mid Cities Parkway, Schertz, TX 78154",
"geometry": {
"type": "Point",
"coordinates": [
-98.2858361,
29.5979442
]
},
"radius": 200
},
"device_id": "5F9C5400-5732-4A02-B3DC-A5E06EE29901",
"distance": 12500,
"driver_handle": "worker-1",
"driver_name": "James Smith",
"duration": 3650,
"embed_url": "https://embed.hypertrack.com/views/orders/order-1?publishable_key=Fw53422gv4apk5CaDU20cZizAAvj0tRJKlVvi3YAt3LshVq443PPgaf_KwkdWq_vS_b3W0o1&source=orders&fulfillment_attempt=0&route-handle=335f0424-4987-427f-abe1-f9bd5764bb11",
"exited_at": "2024-07-21T11:30:05.037Z",
"expected_service_time": 41400,
"fulfillment_attempt": 0,
"ops_group_handle": "default",
"order_handle": "order-1",
"outage_summary": [
{
"category": "behavioural",
"code": "tracking_service_terminated",
"description": "The app is killed by the operating system or force stopped by the worker. The worker should make sure the app is running for successful tracking.\nSometimes the operating system may kill the app to save battery, the app should be added to the whitelist of battery optimization in the device settings",
"distance": null,
"duration": 500,
"label": "Tracking service terminated"
}
],
"planned_at": "2024-07-20T22:00:09.251Z",
"region": {
"country": "United States",
"state": "Kansas"
},
"risk_status": false,
"route_handle": "335f0424-4987-427f-abe1-f9bd5764bb11",
"scheduled_at": "2024-07-21T00:00:00.000Z",
"share_url": "https://trck.at/5qsJtpV1dj",
"started_at": "2024-09-19T14:30:17.059Z",
"status": "completed",
"time_to_first_event": 0.03,
"time_to_first_location": 0.03,
"timezone": "America/Chicago",
"track_mode": "on_time",
"tracking_rate": 0.7252,
"worker_handle": "worker-1"
}
],
"pagination_token": "afV12pdCI6IDEsICJvZmsRwXQiOiAxfQ=="
}
ii. Fetch specific trip detail -> specific order detail (GET /trips/{trip_id} -> GET /orders/{order_handle})
// GET /trips/{trip_id}
{
"trip_id": "335f0424-4987-427f-abe1-f9bd5764bb11",
"started_at": "2024-09-19T14:30:17.057Z",
"completed_at": "2024-09-19T17:10:36.583Z",
"status": "completed",
"device_id": "5F9C5400-5732-4A02-B3DC-A5E06EE29901",
"views": {
"embed_url": "https://embed.hypertrack.com/trips/335f0424-4987-427f-abe1-f9bd5764bb11?publishable_key=Fw53422gv4apk5CaDU20cZizAAvj0tRJKlVvi3YAt3LshVq443PPgaf_KwkdWq_vS_b3W0o1",
"share_url": "https://trck.at/5qsJtpV1dj"
},
"metadata": {
"name": "James Smith",
"worker_type": "shift",
"shift": "shift-1",
"worker_id": "worker-1"
},
"departure": {
"geometry": {
"coordinates": [
-98.523552,
29.419194,
180.3
],
"type": "Point"
},
"address": "Guadalupe Street, Avenida Guadalupe, San Antonio, Bexar County, Texas, 78207, United States"
},
"orders": [
{
"order_id": "order-1",
"metadata": {
"name": "James Smith",
"worker_type": "shift",
"shift": "shift-1",
"worker_id": "[email protected]"
},
"scheduled_at": "2024-09-19T16:30:00.000Z",
"device_id": "5F9C5400-5732-4A02-B3DC-A5E06EE29901",
"completed_at": "2024-09-19T17:10:36.583Z",
"destination": {
"address": "5500 Mid Cities Parkway, Schertz, TX 78154",
"geometry": {
"type": "Point",
"coordinates": [
-98.2858361,
29.5979442
]
},
"radius": 450
},
"arrived_at": "2024-09-19T16:16:13.059Z",
"share_url": "https://trck.at/2Fs4tTy3da",
"status": "completed",
"departure": {
"address": "Guadalupe Street, Avenida Guadalupe, San Antonio, Bexar County, Texas, 78207, United States",
"geometry": {
"coordinates": [
-98.523552,
29.419194,
180.3
],
"type": "Point"
}
},
"duration_at_destination": 3264.0,
"started_at": "2024-09-19T14:30:17.057Z",
"service_time": 0,
"delayed": true,
"arrived": true,
"tracked": true,
"delayed_time": 85573,
"on_time": true,
"completed_at_destination": true,
"capacity": 1,
"end_address": "Mid-Cities Parkway, Schertz, Guadalupe County, Texas, 78154, United States",
"end_location": {
"type": "Point",
"coordinates": [
-98.285672,
29.59711
]
},
"assignment": "on_demand",
"summary": null,
"deviation": 94,
"parking": [],
"checkin": [
{
"geometry": {
"coordinates": [
-98.28559,
29.597195
],
"type": "Point"
},
"score": 1.0,
"timestamp": "2024-09-19T16:16:13.059Z"
}
],
"service_area": [
{
"geometry": {
"coordinates": [
[
[
-98.28558012516034,
29.597385196668665
],
[
-98.2856874902969,
29.597433555110165
],
[
-98.28578768348606,
29.597376690777047
],
]
],
"type": "Polygon"
},
"time_spent": 1750
}
],
"timezone": "America/Chicago",
"driver_handle": "[email protected]"
}
],
"destination": {
"destination_id": "order-1",
"trip_id": "335f0424-4987-427f-abe1-f9bd5764bb11",
"geofence_id": "840674d5-959e-4823-a249-f6aa54bc408a",
"delayed": true,
"arrived": true,
"arrived_at": "2024-09-19T16:16:13.059Z",
"exited_at": "2024-09-19T17:10:37.148Z",
"scheduled_at": "2024-09-19T16:30:00.000Z",
"address": "5500 Mid Cities Parkway, Schertz, TX 78154",
"geometry": {
"type": "Point",
"coordinates": [
-98.2858361,
29.5979442
]
},
"share_url": "https://trck.at/2Fs4tTy3da",
"metadata": {
"name": "James Smith",
"worker_type": "shift",
"shift": "shift-1",
"worker_id": "[email protected]"
},
"estimate": {
"number_of_reroutes": 22,
"number_of_traffic_refreshes": 10,
"traffic_time_per_meter": 0,
"route": {
"distance": 39985,
"duration": 2095,
"updated_at": "2024-09-19T16:21:27.438Z",
"last_sent_duration": 7,
"latest_processed_step_index": 15,
"latest_processed_waypoint_index": 0,
"remaining_distance": 4,
"remaining_duration": 7,
"polyline": {
"type": "LineString",
"coordinates": [
[
-98.28619,
29.59777
],
[
-98.28619,
29.59777
]
]
}
},
"arrive_at": "2024-09-19T18:33:11.850Z"
},
"radius": 450,
"capacity": 1,
"end_address": "Mid-Cities Parkway, Schertz, Guadalupe County, Texas, 78154, United States",
"end_location": {
"type": "Point",
"coordinates": [
-98.285672,
29.59711
]
},
"device_id": "5F9C5400-5732-4A02-B3DC-A5E06EE29901",
"summary": null,
"duration_at_destination": 3264.0
},
"summary": {
"device_id": "5F9C5400-5732-4A02-B3DC-A5E06EE29901",
"locations": {
"type": "LineString",
"coordinates": [
[
-98.285827,
29.596968,
219.35,
"2024-09-19T16:42:31.082Z"
],
[
-98.285672,
29.59711,
219.7,
"2024-09-19T16:45:23.245Z"
],
[
-98.285705,
29.597097,
219.52,
"2024-09-19T16:45:23.245Z"
]
]
},
"markers": [
{
"type": "device_status",
"data": {
"start": {
"recorded_at": "2024-09-19T15:46:01.962Z",
"location": {
"recorded_at": "2024-09-19T16:16:13.059Z",
"geometry": {
"type": "Point",
"coordinates": [
-98.28559,
29.597195
]
}
}
},
"end": {
"recorded_at": "2024-09-19T16:16:13.059Z",
"location": {
"recorded_at": "2024-09-19T16:16:13.059Z",
"geometry": {
"type": "Point",
"coordinates": [
-98.28559,
29.597195
]
}
}
},
"duration": 1811,
"value": "inactive",
"reason": "tracking_service_terminated"
},
"marker_id": "8e122ee6-8dww-4139-96fc-5d18903308e8"
},
{
"type": "device_status",
"data": {
"start": {
"recorded_at": "2024-09-19T16:16:13.059Z",
"location": {
"recorded_at": "2024-09-19T16:16:13.059Z",
"geometry": {
"type": "Point",
"coordinates": [
-98.28559,
29.597195
]
}
}
},
"end": {
"recorded_at": "2024-09-19T17:10:36.583Z",
"location": {
"geometry": {
"type": "Point",
"coordinates": [
-98.285672,
29.59711
]
},
"recorded_at": "2024-09-19T16:45:23.245Z"
}
},
"duration": 3264,
"value": "active",
"address": "Mid-Cities Parkway, Schertz, Guadalupe County, Texas, 78154, United States",
"activity": "stop",
"steps": 0,
"bubble": {
"centroid": [
-98.285855,
29.59711
],
"radius": 148
}
},
"marker_id": "67f31580-h433-46a9-ab60-9674149b4c99"
},
{
"data": {
"arrival": {
"location": {
"geometry": {
"coordinates": [
-98.28559,
29.597195,
0
],
"type": "Point"
},
"recorded_at": "2024-09-19T16:16:13.059Z"
}
},
"geofence": {
"geometry": {
"type": "Point",
"coordinates": [
-98.2858361,
29.5979442
]
},
"geofence_id": "f602abb9-2f5f-4bb7-97d5-8ed336c8a119",
"radius": 450
},
"route_to": {
"duration": 6356,
"distance": 11460
},
"duration": null,
"address": "5500 Mid Cities Parkway, Schertz, TX 78154",
"order_id": "68af25c77b69f10f2ee005e5f016c269_ifsxdTQCiLOjowamHdPXCe7yREA3"
},
"marker_id": "1938c0fa-2433-4552-b96c-ce965f984db8",
"type": "destination"
}
],
"started_at": "2024-09-19T14:30:17.057Z",
"completed_at": "2024-09-19T17:10:36.583Z",
"distance": 11460,
"duration": 9614,
"steps": 0,
"outage_distance": 0,
"outage_duration": 1871,
"duration_at_destination": 3264
},
"capacity": 10,
"optimise_route": false,
"flexible_route": false,
"vehicle_type": "car",
"timezone": "America/Chicago"
}
// GET /orders/{order_handle}
{
"actual_service_time": 29673,
"arrived_at": "2024-07-21T00:34:38.434Z",
"assigned_at": "2024-07-20T22:00:09.565Z",
"capacity_used": 1,
"completed_at": "2024-07-21T11:30:04.930Z",
"completed_at_destination": false,
"created_at": "2024-07-20T22:00:09.251Z",
"destination": {
"address": "Golden Living Convalescent Center, Blake Street, Edwardsville, Wyandotte County, Kansas, 66113, United States",
"checkins": [
{
"count": 1,
"geometry": {
"coordinates": [
-94.80620346228154,
39.060786031602774
],
"type": "Point"
},
"score": 23.019083333333334,
"source": "ht-generated"
},
],
"completions": [],
"geometry": {
"coordinates": [
-94.8168704,
39.0563257
],
"type": "Point"
},
"parkings": [
{
"count": 2,
"geometry": {
"coordinates": [
-94.81645520590858,
39.056779680098245
],
"type": "Point"
},
"score": 56.55160916467568,
"source": "ht-generated"
}
],
"radius": 402,
"service_areas": [
{
"geometry": {
"coordinates": [
[
[
-94.81642054303121,
39.05598781701963
]
]
],
"type": "Polygon"
},
"inclusivity": "10",
"source": "ht-generated"
},
{
"geometry": {
"coordinates": [
[
[
-94.81642054303121,
39.05598781701963
]
]
],
"type": "Polygon"
},
"inclusivity": "25",
"source": "ht-generated"
},
{
"geometry": {
"coordinates": [
[
[
-94.81610705387665,
39.0564284445123
],
[
-94.81642054303121,
39.05598781701963
]
]
],
"type": "Polygon"
},
"inclusivity": "50",
"source": "ht-generated"
},
{
"geometry": {
"coordinates": [
[
[
-94.81642054303121,
39.05598781701963
]
]
],
"type": "Polygon"
},
"inclusivity": "75",
"source": "ht-generated"
},
{
"geometry": {
"coordinates": [
[
[
-94.81642054303121,
39.05598781701963
],
[
-94.81642054303121,
39.05598781701963
]
]
],
"type": "Polygon"
},
"inclusivity": "90",
"source": "ht-generated"
}
]
},
"deviation_from_destination": 102,
"device_id": "5F9C5400-5732-4A02-B3DC-A5E06EE29901",
"distance": 65200,
"driver_handle": "[email protected]",
"duration": 48560,
"embed_url": "https://embed.hypertrack.com/views/orders/order-1?publishable_key=Fw53422gv4apk5CaDU20cZizAAvj0tRJKlVvi3YAt3LshVq443PPgaf_KwkdWq_vS_b3W0o1&source=orders&fulfillment_attempt=0&route-handle=335f0424-4987-427f-abe1-f9bd5764bb11",
"end_location": {
"coordinates": [
-94.817044,
39.057231
],
"type": "Point"
},
"exited_at": "2024-07-21T11:30:04.930Z",
"expected_service_time": 41400,
"fulfillment_attempt": 0,
"ops_group_handle": "default",
"order_handle": "order-1",
"planned_at": "2024-07-20T22:00:09.251Z",
"polyline": {
"coordinates": [
[
-94.83013,
38.888774,
277.7
],
[
-94.830204,
38.888741,
266.35
],
[
-94.817063,
39.057271,
239.74
],
[
-94.817044,
39.057231,
239.74
]
],
"type": "LineString"
},
"region": {
"country": "United States",
"state": "Kansas"
},
"risk_status": false,
"route_handle": "335f0424-4987-427f-abe1-f9bd5764bb11",
"scheduled_at": "2024-07-21T00:00:00.000Z",
"share_url": "https://trck.at/Hd22Dsy",
"start_location": {
"coordinates": [
-94.83013,
38.888774
],
"type": "Point"
},
"started_at": "2024-07-20T22:00:10.175Z",
"status": "completed",
"time_to_first_event": 30.87,
"time_to_first_location": 30.89,
"timeline": [
{
"address": null,
"distance": null,
"duration": null,
"event_id": "6a9083d1-0aed-4d24-9f7d-75a59254e7dd",
"fulfillment_attempt": 0,
"linked_event_ids": null,
"location": null,
"order_handle": "order-1",
"order_id": "25d72b7e-8292-495a-a77f-559c5f0ca9c4",
"order_type": null,
"recorded_at": "2024-07-21T11:30:04.930Z",
"type": "order_service_ended"
},
{
"destination_address": "Golden Living Convalescent Center, Blake Street, Edwardsville, Wyandotte County, Kansas, 66113, United States",
"destination_location": {
"coordinates": [
-94.8168704,
39.0563257
],
"type": "Point"
},
"device_id": null,
"driver_handle": "[email protected]",
"fulfillment_attempt": 0,
"location": null,
"order_handle": "order-1",
"order_type": "",
"recorded_at": "2024-07-21T11:30:04.930Z",
"route_handle": "335f0424-4987-427f-abe1-f9bd5764bb11",
"type": "driver_order_completed"
}
],
"timezone": "America/Chicago",
"track_mode": "on_time",
"tracking_rate": 0.7252,
"visited_destination": true,
"worker_handle": "[email protected]"
}
c. Complete trip -> order (POST /trips/{trip_id}/complete -> POST /orders/{order_handle}/complete)
// POST /trips/{trip_id}/complete
{
"trip_id": "335f0424-4987-427f-abe1-f9bd5764bb11",
"started_at": "2024-09-19T14:30:17.057Z",
"completed_at": "2024-09-19T17:10:36.583Z",
"status": "completed",
"device_id": "5F9C5400-5732-4A02-B3DC-A5E06EE29901",
"views": {
"embed_url": "https://embed.hypertrack.com/trips/335f0424-4987-427f-abe1-f9bd5764bb11?publishable_key=Fw53422gv4apk5CaDU20cZizAAvj0tRJKlVvi3YAt3LshVq443PPgaf_KwkdWq_vS_b3W0o1",
"share_url": "https://trck.at/5qsJtpV1dj"
},
"metadata": {
"name": "James Smith",
"worker_type": "shift",
"shift": "shift-1",
"worker_id": "worker-1"
},
"departure": {
"geometry": {
"coordinates": [
-98.523552,
29.419194,
180.3
],
"type": "Point"
},
"address": "Guadalupe Street, Avenida Guadalupe, San Antonio, Bexar County, Texas, 78207, United States"
},
"orders": [
{
"order_id": "order-1",
"metadata": {
"name": "James Smith",
"worker_type": "shift",
"shift": "shift-1",
"worker_id": "[email protected]"
},
"scheduled_at": "2024-09-19T16:30:00.000Z",
"device_id": "5F9C5400-5732-4A02-B3DC-A5E06EE29901",
"completed_at": "2024-09-19T17:10:36.583Z",
"destination": {
"address": "5500 Mid Cities Parkway, Schertz, TX 78154",
"geometry": {
"type": "Point",
"coordinates": [
-98.2858361,
29.5979442
]
},
"radius": 450
},
"arrived_at": "2024-09-19T16:16:13.059Z",
"share_url": "https://trck.at/2Fs4tTy3da",
"status": "completed",
"departure": {
"address": "Guadalupe Street, Avenida Guadalupe, San Antonio, Bexar County, Texas, 78207, United States",
"geometry": {
"coordinates": [
-98.523552,
29.419194,
180.3
],
"type": "Point"
}
},
"duration_at_destination": 3264.0,
"started_at": "2024-09-19T14:30:17.057Z",
"service_time": 0,
"delayed": true,
"arrived": true,
"tracked": true,
"delayed_time": 85573,
"on_time": true,
"completed_at_destination": true,
"capacity": 1,
"end_address": "Mid-Cities Parkway, Schertz, Guadalupe County, Texas, 78154, United States",
"end_location": {
"type": "Point",
"coordinates": [
-98.285672,
29.59711
]
},
"assignment": "on_demand",
"summary": null,
"deviation": 94,
"parking": [],
"checkin": [
{
"geometry": {
"coordinates": [
-98.28559,
29.597195
],
"type": "Point"
},
"score": 1.0,
"timestamp": "2024-09-19T16:16:13.059Z"
}
],
"service_area": [
{
"geometry": {
"coordinates": [
[
[
-98.28558012516034,
29.597385196668665
],
[
-98.2856874902969,
29.597433555110165
],
[
-98.28578768348606,
29.597376690777047
],
]
],
"type": "Polygon"
},
"time_spent": 1750
}
],
"timezone": "America/Chicago",
"driver_handle": "[email protected]"
}
],
"destination": {
"destination_id": "order-1",
"trip_id": "335f0424-4987-427f-abe1-f9bd5764bb11",
"geofence_id": "840674d5-959e-4823-a249-f6aa54bc408a",
"delayed": true,
"arrived": true,
"arrived_at": "2024-09-19T16:16:13.059Z",
"exited_at": "2024-09-19T17:10:37.148Z",
"scheduled_at": "2024-09-19T16:30:00.000Z",
"address": "5500 Mid Cities Parkway, Schertz, TX 78154",
"geometry": {
"type": "Point",
"coordinates": [
-98.2858361,
29.5979442
]
},
"share_url": "https://trck.at/2Fs4tTy3da",
"metadata": {
"name": "James Smith",
"worker_type": "shift",
"shift": "shift-1",
"worker_id": "[email protected]"
},
"estimate": {
"number_of_reroutes": 22,
"number_of_traffic_refreshes": 10,
"traffic_time_per_meter": 0,
"route": {
"distance": 39985,
"duration": 2095,
"updated_at": "2024-09-19T16:21:27.438Z",
"last_sent_duration": 7,
"latest_processed_step_index": 15,
"latest_processed_waypoint_index": 0,
"remaining_distance": 4,
"remaining_duration": 7,
"polyline": {
"type": "LineString",
"coordinates": [
[
-98.28619,
29.59777
],
[
-98.28619,
29.59777
]
]
}
},
"arrive_at": "2024-09-19T18:33:11.850Z"
},
"radius": 450,
"capacity": 1,
"end_address": "Mid-Cities Parkway, Schertz, Guadalupe County, Texas, 78154, United States",
"end_location": {
"type": "Point",
"coordinates": [
-98.285672,
29.59711
]
},
"device_id": "5F9C5400-5732-4A02-B3DC-A5E06EE29901",
"summary": null,
"duration_at_destination": 3264.0
},
"summary": {
"device_id": "5F9C5400-5732-4A02-B3DC-A5E06EE29901",
"locations": {
"type": "LineString",
"coordinates": [
[
-98.285827,
29.596968,
219.35,
"2024-09-19T16:42:31.082Z"
],
[
-98.285672,
29.59711,
219.7,
"2024-09-19T16:45:23.245Z"
],
[
-98.285705,
29.597097,
219.52,
"2024-09-19T16:45:23.245Z"
]
]
},
"markers": [
{
"type": "device_status",
"data": {
"start": {
"recorded_at": "2024-09-19T15:46:01.962Z",
"location": {
"recorded_at": "2024-09-19T16:16:13.059Z",
"geometry": {
"type": "Point",
"coordinates": [
-98.28559,
29.597195
]
}
}
},
"end": {
"recorded_at": "2024-09-19T16:16:13.059Z",
"location": {
"recorded_at": "2024-09-19T16:16:13.059Z",
"geometry": {
"type": "Point",
"coordinates": [
-98.28559,
29.597195
]
}
}
},
"duration": 1811,
"value": "inactive",
"reason": "tracking_service_terminated"
},
"marker_id": "8e122ee6-8dww-4139-96fc-5d18903308e8"
},
{
"type": "device_status",
"data": {
"start": {
"recorded_at": "2024-09-19T16:16:13.059Z",
"location": {
"recorded_at": "2024-09-19T16:16:13.059Z",
"geometry": {
"type": "Point",
"coordinates": [
-98.28559,
29.597195
]
}
}
},
"end": {
"recorded_at": "2024-09-19T17:10:36.583Z",
"location": {
"geometry": {
"type": "Point",
"coordinates": [
-98.285672,
29.59711
]
},
"recorded_at": "2024-09-19T16:45:23.245Z"
}
},
"duration": 3264,
"value": "active",
"address": "Mid-Cities Parkway, Schertz, Guadalupe County, Texas, 78154, United States",
"activity": "stop",
"steps": 0,
"bubble": {
"centroid": [
-98.285855,
29.59711
],
"radius": 148
}
},
"marker_id": "67f31580-h433-46a9-ab60-9674149b4c99"
},
{
"data": {
"arrival": {
"location": {
"geometry": {
"coordinates": [
-98.28559,
29.597195,
0
],
"type": "Point"
},
"recorded_at": "2024-09-19T16:16:13.059Z"
}
},
"geofence": {
"geometry": {
"type": "Point",
"coordinates": [
-98.2858361,
29.5979442
]
},
"geofence_id": "f602abb9-2f5f-4bb7-97d5-8ed336c8a119",
"radius": 450
},
"route_to": {
"duration": 6356,
"distance": 11460
},
"duration": null,
"address": "5500 Mid Cities Parkway, Schertz, TX 78154",
"order_id": "68af25c77b69f10f2ee005e5f016c269_ifsxdTQCiLOjowamHdPXCe7yREA3"
},
"marker_id": "1938c0fa-2433-4552-b96c-ce965f984db8",
"type": "destination"
}
],
"started_at": "2024-09-19T14:30:17.057Z",
"completed_at": "2024-09-19T17:10:36.583Z",
"distance": 11460,
"duration": 9614,
"steps": 0,
"outage_distance": 0,
"outage_duration": 1871,
"duration_at_destination": 3264
},
"capacity": 10,
"optimise_route": false,
"flexible_route": false,
"vehicle_type": "car",
"timezone": "America/Chicago"
}
// POST /orders/{order_handle}/complete
{
"actual_service_time": 29673,
"arrived_at": "2024-07-21T00:34:38.434Z",
"assigned_at": "2024-07-20T22:00:09.565Z",
"capacity_used": 1,
"completed_at": "2024-07-21T11:30:04.930Z",
"completed_at_destination": false,
"created_at": "2024-07-20T22:00:09.251Z",
"destination": {
"address": "Golden Living Convalescent Center, Blake Street, Edwardsville, Wyandotte County, Kansas, 66113, United States",
"checkins": [
{
"count": 1,
"geometry": {
"coordinates": [
-94.80620346228154,
39.060786031602774
],
"type": "Point"
},
"score": 23.019083333333334,
"source": "ht-generated"
},
],
"completions": [],
"geometry": {
"coordinates": [
-94.8168704,
39.0563257
],
"type": "Point"
},
"parkings": [
{
"count": 2,
"geometry": {
"coordinates": [
-94.81645520590858,
39.056779680098245
],
"type": "Point"
},
"score": 56.55160916467568,
"source": "ht-generated"
}
],
"radius": 402,
"service_areas": [
{
"geometry": {
"coordinates": [
[
[
-94.81642054303121,
39.05598781701963
]
]
],
"type": "Polygon"
},
"inclusivity": "10",
"source": "ht-generated"
},
{
"geometry": {
"coordinates": [
[
[
-94.81642054303121,
39.05598781701963
]
]
],
"type": "Polygon"
},
"inclusivity": "25",
"source": "ht-generated"
},
{
"geometry": {
"coordinates": [
[
[
-94.81610705387665,
39.0564284445123
],
[
-94.81642054303121,
39.05598781701963
]
]
],
"type": "Polygon"
},
"inclusivity": "50",
"source": "ht-generated"
},
{
"geometry": {
"coordinates": [
[
[
-94.81642054303121,
39.05598781701963
]
]
],
"type": "Polygon"
},
"inclusivity": "75",
"source": "ht-generated"
},
{
"geometry": {
"coordinates": [
[
[
-94.81642054303121,
39.05598781701963
],
[
-94.81642054303121,
39.05598781701963
]
]
],
"type": "Polygon"
},
"inclusivity": "90",
"source": "ht-generated"
}
]
},
"deviation_from_destination": 102,
"device_id": "5F9C5400-5732-4A02-B3DC-A5E06EE29901",
"distance": 65200,
"driver_handle": "[email protected]",
"duration": 48560,
"embed_url": "https://embed.hypertrack.com/views/orders/order-1?publishable_key=Fw53422gv4apk5CaDU20cZizAAvj0tRJKlVvi3YAt3LshVq443PPgaf_KwkdWq_vS_b3W0o1&source=orders&fulfillment_attempt=0&route-handle=335f0424-4987-427f-abe1-f9bd5764bb11",
"end_location": {
"coordinates": [
-94.817044,
39.057231
],
"type": "Point"
},
"exited_at": "2024-07-21T11:30:04.930Z",
"expected_service_time": 41400,
"fulfillment_attempt": 0,
"ops_group_handle": "default",
"order_handle": "order-1",
"planned_at": "2024-07-20T22:00:09.251Z",
"polyline": {
"coordinates": [
[
-94.83013,
38.888774,
277.7
],
[
-94.830204,
38.888741,
266.35
],
[
-94.817063,
39.057271,
239.74
],
[
-94.817044,
39.057231,
239.74
]
],
"type": "LineString"
},
"region": {
"country": "United States",
"state": "Kansas"
},
"risk_status": false,
"route_handle": "335f0424-4987-427f-abe1-f9bd5764bb11",
"scheduled_at": "2024-07-21T00:00:00.000Z",
"share_url": "https://trck.at/Hd22Dsy",
"start_location": {
"coordinates": [
-94.83013,
38.888774
],
"type": "Point"
},
"started_at": "2024-07-20T22:00:10.175Z",
"status": "completed",
"time_to_first_event": 30.87,
"time_to_first_location": 30.89,
"timeline": [
{
"address": null,
"distance": null,
"duration": null,
"event_id": "6a9083d1-0aed-4d24-9f7d-75a59254e7dd",
"fulfillment_attempt": 0,
"linked_event_ids": null,
"location": null,
"order_handle": "order-1",
"order_id": "25d72b7e-8292-495a-a77f-559c5f0ca9c4",
"order_type": null,
"recorded_at": "2024-07-21T11:30:04.930Z",
"type": "order_service_ended"
},
{
"destination_address": "Golden Living Convalescent Center, Blake Street, Edwardsville, Wyandotte County, Kansas, 66113, United States",
"destination_location": {
"coordinates": [
-94.8168704,
39.0563257
],
"type": "Point"
},
"device_id": null,
"driver_handle": "[email protected]",
"fulfillment_attempt": 0,
"location": null,
"order_handle": "order-1",
"order_type": "",
"recorded_at": "2024-07-21T11:30:04.930Z",
"route_handle": "335f0424-4987-427f-abe1-f9bd5764bb11",
"type": "driver_order_completed"
}
],
"timezone": "America/Chicago",
"track_mode": "on_time",
"tracking_rate": 0.7252,
"visited_destination": true,
"worker_handle": "[email protected]"
}
There's so much more to do with the new Orders API, so please check the Orders API references
3. Migrate your UI
We've been chipping away at creating a much better UI experience for your Ops teams. If you are users of our embed and trckat views, you can make the changes below ot get the latest experience with your Orders.
https://embed.hypertrack.com/trips/{trip_id}?publishable_key={your_key}
https://embed.hypertrack.com/views/orders/{order_handle}?publishable_key={your_key}
Here is what the new world look like!
For trckat customer links, you don't need any change!
4. Webhook Trips -> Orders
While there are some common webhooks you'll continue to receive, webhooks of type trip will no longer be sent. We instead provide a set of order webhooks as listed below.
Common webhooks:
Order webhooks:
- Order Started
- Order First ETA
- Order ETA Change
- Order Delayed
- Order Arrived
- Order Exited
- Order Completed
You can find more information on Order webhooks here
Voila! Following these steps will move you to the new HyperTrack world!
Migrations are hard and the HyperTrack team is with you every step of the way, so feel free to reach out to us and we'll ensure that your experience is as seamless as possible.
Updated about 2 months ago