Assign orders to Nearby users

Introduction

Live location is an important input to any on-demand dispatch, assignment and routing system.

On-demand work may be assigned to workers that are out and about fulfilling other work, or are physically distributed in a region. Assignment 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 search

To help with on-demand assignment use cases, HyperTrack provides Nearby API. Nearby search locates app users, figures out which ones are nearest to the location of interest, and returns them as a sorted list with nearest first by drive ETA.

Nearby Dashboard

Use this POST Nearby API request to find available app users near work location.

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

The POST request contains the following required parameters:

  • location represents the location near which you want to find available app users. E.g. location of pickup, store, service, warehouse, etc.;
  • radius indicates, in meters, a circular area within which nearby app users can be found. E.g. search within 3km;
  • last_updated_within specifies, in hours, the time within which the latest location sent by devices needs to be considered. E.g. if this value is 24 then all devices which have sent their latest locations in last 24 hrs would be considered in response. If this parameter is unspecified, by default it will return devices with their last known locations recorded in the past hour;
  • deep performs an asynchronous call, when set to true, and attempts to locate devices that have stopped tracking or are disconnected. This is done through quiet push notifications sent to devices to resume tracking;
  • metadata filters nearby search results by app users with matching device metadata. E.g. skill, team, store, vehicle, category, etc. This is an optional parameter;
  • devices is an optional list of device IDs to restrict nearby search results to only these devices. E.g. are app users in the vicinity of the request location.
curl -X POST \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/devices/nearby
important

You do not need to continually track devices to use Nearby API. Deep search lets you include devices on which you have stopped tracking. However, this is an async call.

Nearby API uses a payload structure like this below.

{
"location": {
"coordinates": [
-122.402007, 37.792524
],
"type" : "Point"
},
"radius" : 1000,
"deep": true,
"metadata": {
"type": "gig_work",
"skill": "pro",
"vehicle": "van"
}
}

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

The metadata parameter is optional to filter drivers of a certain type, skill, vehicle, or any other app user device metadata set by you.

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,
"deep": true,
"devices":[
"00112233-531B-4FC5-AAC5-3DB7886FE3D2",
"00112233-E0A7-4217-8175-888CA30C5225"
]
}

Please review working code examples written in Node.js and Python to copy and re-use to make requests via Nearby API.

Please reach out to us if you would like support in any other programming language you would like to use.

Search request

const request = require("request");
const payload = {
// location of the work order where you want to find
// nearest app users.
"location": {
"coordinates": [
-122.503, 37.761
],
"type" : "Point"
},
// limit nearby devices to 2 km radius
"radius" : 1000,
// Perform a request to only get devices with locations recorded in the past hour
"deep": false,
// metadata below is optional and is a way to filter
// devices that may match this criteria.
// if you are trying against a small number of devices
// without metadata being set, please
// remove the metadata filter below from the payload.
"metadata": {
"gig_type": "on_demand_work",
"order": "on_demand_work_order"
}
}
const options = {
method: "POST",
url: "https://v3.api.hypertrack.com/devices/nearby/",
auth: {
user: AccountId,
password: SecretKey
},
json: true,
body: payload
};
request(options, function(err, res, body) {
console.error('error:', err);
console.log('statusCode:', res && res.statusCode);
// The body will contain the response with request_url that you will use to get
// devices near this location.
console.log(body);
});

Upon making request with above payload, you will get an HTTP 200 response with a payload explained in the next section.

Request response

Upon making the above HTTP POST request, you will get an HTTP 200 response with this below payload. You will see three device records returned ordered by proximity with the first one being the closest.

{'data': [{'device_id': '3C2F245D-FF16-480F-9C25-30E248DF5C35',
'device_info': {'device_brand': 'Apple',
'device_model': 'iPhone 12',
'name': 'Thomas iPhone',
'network_operator': 'Carrier',
'os_hardware_identifier': None,
'os_name': 'iOS',
'os_version': '14.6',
'sdk_version': '4.8.0',
'timezone': 'America/Los_Angeles'},
'distance': 18134.3,
'duration': 1159.6,
'location': {'geometry': {'coordinates': [-122.304217,
37.874884,
13.38],
'type': 'Point'},
'recorded_at': '2021-05-27T07:27:46.488Z'},
'metadata': {'foo': 'bar'}},
{'device_id': 'E7037DB1-587F-4307-8BBA-8D58ED018901',
'device_info': {'device_brand': 'Apple',
'device_model': 'iPhone 11 Pro Max',
'name': 'Kashyap',
'network_operator': 'AT&T',
'os_hardware_identifier': None,
'os_name': 'iOS',
'os_version': '14.4.2',
'sdk_version': '4.8.0',
'timezone': 'America/Los_Angeles'},
'distance': 22684.6,
'duration': 1660,
'location': {'geometry': {'coordinates': [-122.272492,
37.903949,
256.44],
'type': 'Point'},
'recorded_at': '2021-05-27T06:52:05.621Z'},
'metadata': {'driver_id': 'Kashyap'}},
{'device_id': '9689E852-F27B-3798-B0CE-319BAEF65F99',
'device_info': {'device_brand': 'OnePlus',
'device_model': 'ONEPLUS A3003',
'name': 'Aashish',
'network_operator': 'T-MOBILE',
'os_hardware_identifier': None,
'os_name': 'Android',
'os_version': '9',
'sdk_version': '4.5.3',
'timezone': 'America/Los_Angeles'},
'distance': 65500.6,
'duration': 3116.1,
'location': {'geometry': {'coordinates': [-122.088151,
37.376027,
8.4],
'type': 'Point'},
'recorded_at': '2020-11-10T02:47:06.310Z'},
'metadata': None}]}
"status":"completed"
}

Here data is the list of devices which are ranked based on their distance from work location (nearest first). Note that this API request only returns devices that were known to record locations in the past hour at the time of this HTTP POST Nearby API request.

Attributes such as distance and duration in the API response above indicate distance and time that the app user identified by 00112233-FFA6-404C-A30F-27B38836A887 will need to get to drive to get to the dispatch location.

Nearby search on user location history

Nearby API helps you search for the nearest qualified user to assign the job. We have extended this API to search for the nearest location that a user visited within the last N hours. This way, you could search for the user's recent affinity to that place before assigning the job, or verify whether the user visited the place you expected them to after the job is done.

curl \
-X POST \
-u {AccountId}:{SecretKey} \
https://v3.api.hypertrack.com/devices/nearby \
-H 'Content-Type: application/json' \
--data-raw '
{
"location": {
"coordinates": [
-122.402007,
37.792524
],
"type" : "Point"
},
"historic_locations_within": 24,
"device_id": "00112233-531B-4FC5-AAC5-3DB7886FE3D2"
}'

Returns:

{
"data": [
{
"location": {
"geometry": {
"type": "Point",
"coordinates": [
-122.402007,
37.792524
]
},
"recorded_at": "2021-01-01T00:01:02.123Z"
},
"device_id": "00112233-531B-4FC5-AAC5-3DB7886FE3D2",
"device_info": {
"timezone": "America/Los_Angeles",
"os_name": "iOS",
"device_brand": "Apple",
"sdk_version": "4.6.0",
"device_model": "iPhone 12",
"network_operator": "Carrier",
"name": "iPhone",
"os_version": "14.4",
"os_hardware_identifier": "asdfasdf"
},
"metadata": {
"worker_id": "1234"
},
"distance": 1234.17,
"duration": 456
}
]
}

Asynchronous deep search

An asynchronous deep search includes devices that have stopped tracking or may be disconnected. To use this option, set the deep flag to true.

This workflow executes as follows:

Nearby API Workflow

  1. Make an HTTP POST request to find available users near work location.
  2. Nearby API POST request returns a response that contains request_url string. This is the Nearby API GET call you need to invoke to obtain nearby devices.
  3. 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.
  4. In addition to GET /devices/nearby API, you will also get notified about the completion of a request via webhook notification. Once this notification is received, you can make a final call to fetch nearby devices as described in the above step.

Deep search request

Please review working code examples written in Node.js and Python to copy and re-use to make requests via Nearby API.

const request = require("request");
const payload = {
// location of the work order where you want to find
// nearest app users.
"location": {
"coordinates": [
-122.503, 37.761
],
"type" : "Point"
},
// limit nearby devices to 2 km radius
"radius" : 1000,
// metadata below is optional and is a way to filter
// devices that may match this criteria.
// if you are trying against a small number of devices
// without metadata being set, please
// remove the metadata filter below from the payload.
"metadata": {
"gig_type": "on_demand_work",
"order": "on_demand_work_order"
}
}
const options = {
method: "POST",
url: "https://v3.api.hypertrack.com/devices/nearby/",
auth: {
user: AccountId,
password: SecretKey
},
json: true,
body: payload
};
request(options, function(err, res, body) {
console.error('error:', err);
console.log('statusCode:', res && res.statusCode);
// The body will contain the response with request_url that you will use to get
// devices near this location.
console.log(body);
});

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

Request response

Nearby API POST request returns a response that contains request_url string. This is the 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'}
}

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": "on demand work"
}
"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. These are nearest available app users to choose from in your application workflow.

Fetching 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":{
"timezone": "Europe/Berlin",
"os_name": "iOS",
"device_brand": "Apple",
"sdk_version": "3.7.0",
"device_model": "iPhone 8 Plus",
"network_operator": "TMobile",
"name": "iPhone Franz",
"os_version": "13.1.2",
"os_hardware_identifier": "123e4567-e89b-12d3-a456-426614174000"
},
"metadata":{
"key_1":"value_1"
},
"location":{
"recorded_at":"2020-04-29T02:25:54.906839Z",
"geometry":{
"coordinates":[
35.10654,
47.847252,
610
],
"type":"Point"
},
},
"distance": 1283,
"duration": 156
}
],
"status":"pending"
}

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

Attributes such as distance and duration in the API response above indicate distance and time that the app user identified by 00112233-FFA6-404C-A30F-27B38836A887 will need to get to drive to get to the dispatch location.

Please review working code examples written in Node.js and Python to copy and re-use to retrieve results from previous requests made via Nearby API. Please reach out to us if you would like support in any other programming language you would like to use.

const request = require("request");
const options = {
method: "GET",
// This is an example request URL that you get from
// the call above. Please make a change to
// to define your own url value.
url: "https://v3.api.hypertrack.com/devices/nearby?request_id=44ad6f3b-663f-4b29-ad60-b15d367a7bdb&limit=100",
auth: {
user: AccountId,
password: SecretKey
}
};
request(options, function(err, res, body) {
console.error('error:', err);
console.log('statusCode:', res && res.statusCode);
// This will contain list of devices found to be near the location
// specified in the above request. The output is explained
// in the above section ( "Fetching request results" )
let json = JSON.parse(body);
console.log(json);
});

Questions?

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