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.
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:
The POST request contains the following required parameters:
locationrepresents, for example, a potential gig location near which you want to find available gig workers;
radiusindicates, in meters, a circular area within which nearby gig workers can be found;
metadatafor 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;
devicesis 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.
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.
In the above payload example
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.
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.
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.
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.
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
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.
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.
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.