Assign orders to Nearby drivers

Introduction

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

On-demand work may be assigned to drivers 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 driver. Knowing the live location of available drivers, 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.

Driver availability

To ensure your drivers are included in Nearby Search results they need to be made available as described here. If you have already completed this step proceed to the next step.

Nearby search

To help with on-demand assignment use cases, HyperTrack provides Nearby API. Nearby search locates drivers, 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/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;
  • profile_filter filters nearby search results by app users with matching user profile. 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/nearby
important

You do not need to continually track devices to use Nearby API. HyperTrack provides Nearby Availability feature that allows you to obtain nearby search results without needing to track your app users. Please contact us to learn more.

Nearby API uses a payload structure like this below.

{
"location": {
"coordinates": [
-122.402007, 37.792524
],
"type" : "Point"
},
"radius" : 1000,
"profile_filter": {
"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 profile_filter parameter is optional to filter drivers of a certain type, skill, vehicle, or any other app user user profile set by you.

In place of profile_filter, 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"
]
}

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
// 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.
"profile_filter": {
"gig_type": "on_demand_work",
"order": "on_demand_work_order"
}
}
const options = {
method: "POST",
url: "https://v3.api.hypertrack.com/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/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
}
]
}

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.