Dispatch work to Nearby devices
Introduction
Live location is an important input to an on-demand dispatch algorithm to assign work to the nearest available app user.
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
To help with dispatching work use cases, HyperTrack provides Nearby API.
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. This API can be called either synchronously or asynchronously.
Synchronous API invocation
This option can return immediately results that include devices are currently tracking.
In this case, the API request gets results in the immediate API response payload. Only devices with recently recorded locations as specified in the last_updated_within
and located in proximity to the dispatch location will be returned in the API call.
Asynchronous workflow overview
In summary, an asynchronous invocation of Nearby API achieves the goal of retrieving devices that are not currently tracking in addition to actively tracking. You may use deep
flag in the API request to indicate desire to retrieve also locations of currently inactive devices.
This workflow executes as follows:
- Make an HTTP POST request to find available users near work location.
- 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. - 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. - 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.
Making a request to get nearby app users.
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, for example, a potential work dispatch location near which you want to find available app users;radius
indicates, in meters, a circular area within which nearby app users can be found;last_updated_within
allows to specify time range (in hours) within which the latest location sent by devices needs to be considered; for example 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 not specified, by default it will return devices with their last known locations recorded in the past hour;deep
means that if it istrue
then perform an asynchronous call to collect devices that are both active and inactive. Otherwise, by default, this invocation will be synchronous and return only those devices that have sent locations inlast_updated_within
time frame;metadata
for app user's devices that can be used to filter nearby search results; these metadata can represent attributes describing your 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 app user's device is in the vicinity of the request area, you may submit the app user's device id to get an answer.
important
You do not need to continually track devices to use 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.
Nearby API uses a payload structure like this below.
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 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.
Code example: making a synchronous request to get nearby app users
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.
- JavaScript
- Python
Upon making request with above payload, you will get an HTTP 200 response with a payload explained in the next section.
Request response data
Upon making the above HTTP POST request, you will get an HTTP 200 response with this below payload.
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.
Code example: making an asynchronous request to get nearby app users
Please review working code examples written in Node.js and Python to copy and re-use to make requests via Nearby API.
- JavaScript
- Python
Upon making request with above payload, you will get an HTTP 202 response with the below payload like this below.
Return response data
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.
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.
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.
Code example: fetching request results
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.
- JavaScript
- Python
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.
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 hearest available app users to choose from in your application workflow.
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.