Dispatch to nearest available

Introduction

Live location is an important input to dispatch algorithms.

On-demand work may be assigned to workers that are out and about fulfilling other work, or are physically distributed in a region. Dispatch systems use a number of factors to allocate work to a worker. Knowing the live location of available workers, and ranking them as nearest first from the first point of fulfillment (pickup, visit, delivery or gig location), becomes a critical input to dispatch systems.

In the world of scheduled deliveries with fixed route plans, it is usual to have exceptions on the field (urgent orders, priority work, unexpected mishaps) where routes need to be dynamically modified and new work added to routes on the fly.

Nearby API helps dispatch work for such use cases.

Locating nearby app users

Nearby API locates app users on demand, figures out which ones are nearest to the location of interest, and returns them as an ordered list with nearest first.

note

This API is in limited Beta with select customers. Please contact us to get access. Additional fees may apply when the API is in production.

Making a request to get nearby app users

Use this POST Device Nearby API request:

POST   https://v3.api.hypertrack.com/devices/nearby

The POST request contains the following required parameters:

  • location represents, for example, a potential gig location near which you want to find available gig workers;
  • radius indicates, in meters, a circular area within which nearby gig workers can be found;
  • metadata for gig worker's devices that can be used to filter nearby search results; these metadata can represent attributes describing your gig workers, such as a team assignment, gig category, etc. It's an optional parameter;
  • devices is an optional list of device ids that can also be used to restrict nearby search results only for these devices. For example, to answer a question if a given's worker device is in the vicinity of the request area, you may submit the worker's device id to get an answer.
curl -X POST \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/devices/nearby
important

You do not need to continually track devices to use Devices Nearby API. Devices can remain in an inactive state.

HyperTrack will reach out to all devices you are interested in and determine their current locations and deliver this information to you.

Devices nearby API uses a payload structure like this below.

{
"location": {
"coordinates": [
-122.402007, 37.792524
],
"type" : "Point"
},
"radius" : 1000,
"metadata": {
"team": "san_francisco",
"gig_type": "delivery"
}
}

In the above payload example location and radius of represent a circular area of 2km in diameter centered at a gig location -122.402007, 37.792524 within which devices are considered nearby.

The metadata parameter is optional to apply filtering (e.g only looking for devices within a city/region) In place of metadata, filtered list of device_ids can also be be provided directly via devices parameter as shown below.

{
"location": {
"coordinates": [
-122.402007, 37.792524
],
"type" : "Point"
},
"radius" : 1000,
"devices":[
"00112233-531B-4FC5-AAC5-3DB7886FE3D2",
"00112233-E0A7-4217-8175-888CA30C5225"
]
}

Upon making request with above payload, you will get an HTTP 202 response with the below payload like this below.

Return response data

Devices Nearby API POST request returns a response that contains request_url string. This is the Devices Nearby API GET call you need to invoke to obtain nearby devices.

{
"request_url": 'https://v3.api.hypertrack.com/devices/nearby?request_id=09f63b10-9bbc-4b24-af1a-d8ac84644fcc&limit=100'}
}

Fetching request results

In order to fetch nearby devices corresponding to the above request, make a GET request to the above request_url sent in POST API response.

GET   https://v3.api.hypertrack.com/devices/nearby?request_id={request_id}&limit={limit}&{pagination_token}

Parameters limit and pagination_token are optional to paginate the response.

Upon making the above request, you will get an HTTP 200 response with this below payload. Make a note of status field which indicates whether the request is in pending or completed status.

{
"data":[
{
"device_info":{
"device-model":"IPhone X",
...
"os-version":"12.1.4",
"sdk-version":"test app",
"app-version-number":123,
"device-hardware":"test device model"
},
"metadata":{
"key_1":"value_1"
},
"location":{
"recorded_at":"2020-04-29T02:25:54.906839Z",
"device_id":"00112233-FFA6-404C-A30F-27B38836A887",
"bearing":90,
"accuracy":15.02,
"geometry":{
"coordinates":[
35.10654,
47.847252,
610
],
"type":"Point"
},
"id":"01394a78-d3c8-45cb-a440-d8ae39009065",
"speed":0.2,
"arrived_at":"2020-04-29T02:25:55.103000Z"
},
"health":{
"data":"{\"value\": \"outage.stopped\", \"outage_reason\": \"stopped_programmatically\"}",
"recorded_at":"2020-04-29T02:25:49.340Z"
},
"nearby_devices_request_id":"09f63b10-9bbc-4b24-af1a-d8ac84644fcc",
"device_id":"00112233-FFA6-404C-A30F-27B38836A887",
"account_id":"11902a90-64ab-4b78-b903-099fcdb93242",
"device_status":{
"active":{
"activity":"unknown",
"recorded_at":"2020-04-29T02:25:54.906839Z"
}
}
}
],
"status":"pending"
}

Here data is the list of devices which are ranked based on their distance from gig location (nearest first). You may poll this GET request_url as additional devices are found and identified nearby.

Receiving request completion notification

In addition to GET /devices/nearby API, you will also get notified about the completion of a request via webhook notification with below payload example structure.

{
"created_at": "2020-04-29T02:25:59.906839Z",
"type": "nearby_devices_request",
"data": {
"value": "completed",
"request_id": "09f63b10-9bbc-4b24-af1a-d8ac84644fcc",
"location": {
"coordinates": [
-122.402007, 37.792524
],
"type" : "Point"
},
"metadata": {
"team": "san_francisco",
"gig_type": "delivery"
}
"radius": 1000
},
'version': '2.0.0'
}

Once you receive the notification, you will be able to make a final GET request_url call to obtain a list of devices that HyperTrack determines to be nearby the location of interest.

Questions?

If you would like help with dispatch use cases using live location, questions or comments on any of the topics above, please do not hesitate to contact us.