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:

Nearby API Workflow

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 is true 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 in last_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.

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. 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.

{
    "location": {
        "coordinates": [
          -122.402007, 37.792524
        ],
        "type" : "Point"
    },
    "radius" : 1000,
    "deep": true,
    "metadata": {
        "gig_type": "on_demand_work",
        "order": "on_demand_work_order"
    }
}

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.

{
    "location": {
        "coordinates": [
          -122.402007, 37.792524
        ],
        "type" : "Point"
    },
    "radius" : 1000,
    "deep": true,
    "devices":[
      "00112233-531B-4FC5-AAC5-3DB7886FE3D2",
      "00112233-E0A7-4217-8175-888CA30C5225"
      ]
}

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

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 data

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

{
   "data":[
      {
         "device_info":{
            "device-model":"IPhone X",
            ...
            "os-version":"12.1.4",
            "sdk-version":"test app",
            "app-version-number":123,
            "device-hardware":"test device model"
         },
         "metadata":{
            "key_1":"value_1"
         },
         "location":{
            "recorded_at":"2020-04-29T02:25:54.906839Z",
            "device_id":"00112233-FFA6-404C-A30F-27B38836A887",
            "bearing":90,
            "accuracy":15.02,
            "geometry":{
               "coordinates":[
                  35.10654,
                  47.847252,
                  610
               ],
               "type":"Point"
            },
            "id":"01394a78-d3c8-45cb-a440-d8ae39009065",
            "speed":0.2,
            "arrived_at":"2020-04-29T02:25:55.103000Z"
         },
         "health":{
            "data":"{\"value\": \"outage.stopped\", \"outage_reason\": \"tracking_stopped\"}",
            "recorded_at":"2020-04-29T02:25:49.340Z"
         },
         "nearby_devices_request_id":"09f63b10-9bbc-4b24-af1a-d8ac84644fcc",
         "device_id":"00112233-FFA6-404C-A30F-27B38836A887",
         "account_id":"11902a90-64ab-4b78-b903-099fcdb93242",
         "device_status":{
            "active":{
               "activity":"unknown",
               "recorded_at":"2020-04-29T02:25:54.906839Z"
            }
         },
         "distance": 1283,
         "duration": 156
      }
   ],
   "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.

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

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.

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.

{
    "request_url": 'https://v3.api.hypertrack.com/devices/nearby?request_id=09f63b10-9bbc-4b24-af1a-d8ac84644fcc&limit=100'}
}

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.

{
   "data":[
      {
         "device_info":{
            "device-model":"IPhone X",
            ...
            "os-version":"12.1.4",
            "sdk-version":"test app",
            "app-version-number":123,
            "device-hardware":"test device model"
         },
         "metadata":{
            "key_1":"value_1"
         },
         "location":{
            "recorded_at":"2020-04-29T02:25:54.906839Z",
            "device_id":"00112233-FFA6-404C-A30F-27B38836A887",
            "bearing":90,
            "accuracy":15.02,
            "geometry":{
               "coordinates":[
                  35.10654,
                  47.847252,
                  610
               ],
               "type":"Point"
            },
            "id":"01394a78-d3c8-45cb-a440-d8ae39009065",
            "speed":0.2,
            "arrived_at":"2020-04-29T02:25:55.103000Z"
         },
         "health":{
            "data":"{\"value\": \"outage.stopped\", \"outage_reason\": \"tracking_stopped\"}",
            "recorded_at":"2020-04-29T02:25:49.340Z"
         },
         "nearby_devices_request_id":"09f63b10-9bbc-4b24-af1a-d8ac84644fcc",
         "device_id":"00112233-FFA6-404C-A30F-27B38836A887",
         "account_id":"11902a90-64ab-4b78-b903-099fcdb93242",
         "device_status":{
            "active":{
               "activity":"unknown",
               "recorded_at":"2020-04-29T02:25:54.906839Z"
            }
         },
         "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.

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

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);
});

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.

 {
    "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 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.

Introduction#

Nearby API#

Synchronous API invocation#

Asynchronous workflow overview#

Making a request to get nearby app users.#

important

Code example: making a synchronous request to get nearby app users#

Request response data#

Code example: making an asynchronous request to get nearby app users#

Return response data#

Fetching request results#

Code example: fetching request results#

Receiving request completion notification#

Questions?#