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.
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.
Use this POST Nearby API request to find available app users near work location.
The POST request contains the following required parameters:
locationrepresents the location near which you want to find available app users. E.g. location of pickup, store, service, warehouse, etc.;
radiusindicates, in meters, a circular area within which nearby app users can be found. E.g. search within 3km;
last_updated_withinspecifies, 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_filterfilters nearby search results by app users with matching user profile. E.g. skill, team, store, vehicle, category, etc. This is an optional parameter;
devicesis 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.
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.
In the above payload example
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.
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.
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.
Upon making request with above payload, you will get an HTTP 200 response with a payload explained in the next section.
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 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
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.
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.