Manage on-demand logistics

Introduction

We have now entered the second decade of a large variety of on-demand logistics services, such as ridesharing, gig work and on-demand delivery.

These on-demand logistics services include moving, parking, courier, groceries, flowers, dog walks, massages, dry cleaning, vets, medicines, car washes, roadside assistance, cannabis and more.

Through these on-demand platforms, supply and demand are aggregated online for services to be fulfilled offline.

Creating an on-demand solution

In this tutorial, we consider a ridesharing use case. Learnings from this tutorial can be applied to many of the on-demand logistics services listed above.

A customer requests a pick up at a location chosen by the customer. The pickup order is dispatched to drivers who are available within an area of reach. One of the drivers picks up the customer's request and proceeds to the customer's location for a pick up. Once the pick up takes place, the driver will transport the customer to a destination chosen by the customer.

Ride sharing experience

On-demand solution steps

We will go through the following steps:

On-demand solution components

Before we proceed to go through the steps required to create an on-demand solution, we need to build the following components:

  • Customer app
  • Driver app
  • On-demand logistics backend

Customer app

Customer app is a mobile app which helps achieve the following:

  • Displaying nearby drivers as an option offered to the customer.
  • Order request that can be sent to the on-demand logistics backend
  • Tracking driver to the customer's pickup location. To achieve this, the customer's app uses Views SDK to provide real-time location updates to the customer
  • Track customer's trip to the customer's destination. The customer's app uses Views SDK to provide real-time location updates to the customer
  • Display trip summary to the customer after the trip completion. This is done with Views SDK
note

Customer app does not track location of the customer. No location permissions are necessary to be requested from the customer to support the tracking experience.

Driver app

Driver app is another mobile app which helps achieve the following:

  • Driver registration and authentication with your on-demand logistics backend
  • Displaying assigned order request to the driver
  • Order request acceptance
  • Generating location data for the customer to track the driver to both pickup destination as well as to drop off destination
  • Pickup and drop off order completion and sign off
note

Driver app tracks the driver. Location and motion permissions are necessary to be requested from the driver to track an order.

On-demand logistics backend

On-demand logistics backend is built to achieve the following:

  • Customer and driver registration and management
  • Customer order requests
  • Find nearby drivers and assign customer order requests with Nearby API
  • Receive driver acceptance for orders
  • Manage trips to customer's pickup and drop off locations with Trips API

Customer order

On-demand customer downloads and installs the customer app and signs in. Customer can use the app to book an order.

Customer registration

Your customer app and on-demand logistics backend implement customer registration by capturing customer's identity and verifying customer's credentials. You store customer's information in your on-demand logistics backend. The customer's identity and credentials are used to authenticate customer's order request and present to assigned drivers.

Order execution

The customer picks a location and orders a pickup to go to a destination. The on-demand logistics backend receives the order and stores it in its database for the next step. This step will involve finding available drivers near pickup location as explained below.

Driver registration

The driver downloads the driver app, registers and authenticates to your on-demand logistics backend. In the process of registration, driver app captures driver's device_id from HyperTrack SDK which is sent to on-demand logistics backend along with the driver's identity and credentials.

To add location tracking to your on-demand solution, you must add HyperTrack SDK to your driver app. Please use one of the following options.

Enable location tracking in driver app

Follow these instructions to install the SDK.

Identify drivers

In order to provide a great on-demand experience for customers, add driver identity as the name for your driver's device. The driver's name will show in your customer's app.

Review instructions on how to set device name and metadata and make a decision on what works best for your on-demand app.

For example, the device name can be a driver's name or some other identifier you use in your system with example below:

{
"name": "Kanav",
"metadata": {
"model": "i3",
"make": "BMW",
"color": "blue"
}
}

Locate nearby drivers

Live location is an important input to the driver dispatch algorithm to request a pickup and dropoff.

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.

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.

note

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 drivers

Use this POST Device Nearby API request to find available drivers near pickup location.

POST   https://v3.api.hypertrack.com/devices/nearby

The POST request contains the following required parameters:

  • location represents, for example, a potential gig location near which you want to find available gig workers;
  • radius indicates, in meters, a circular area within which nearby gig workers can be found;
  • metadata for 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;
  • 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's worker device is in the vicinity of the request area, you may submit the worker'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 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.

{
"location": {
"coordinates": [
-122.402007, 37.792524
],
"type" : "Point"
},
"radius" : 1000,
"metadata": {
"gig_type": "ridesharing",
"order": "rider_A_pickup_at_location_X"
}
}

In the above payload example location and 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.

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,
"devices":[
"00112233-531B-4FC5-AAC5-3DB7886FE3D2",
"00112233-E0A7-4217-8175-888CA30C5225"
]
}

Code example: making a request to get nearby drivers

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.

const request = require("request");
const payload = {
// location of the customer pickup order where you want to find
// nearest drivers.
"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": "ridesharing",
"order": "rider_A_pickup_at_location_X"
}
}
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

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.

{
"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\": \"stopped_programmatically\"}",
"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"
}
}
}
],
"status":"pending"
}

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

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.

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": "delivery"
}
"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 drivers that can be presented with the customer's request.

Assign and accept order

Once nearby available drivers located, customer's request is assigned to available drivers by your on-demand logistics backend and presented in their driver app. One of the drivers can accept the order and drive to the pickup location.

Assign order request to available drivers

On-demand logistics backend receives results of Nearby API and assigns order request to the nearest available drivers. Your driver app presents the pickup order in the screen to each of these available drivers, along with the identity of the customer and pickup location.

Tracking Experience

Driver acceptance

As illustrated in the image above, driver app gives an opportunity for the driver to accept an assigned order. Once the driver accepts the order, on-demand logistics backend proceeds to create a trip for the driver to the pickup location as explained below.

Track driver to customer pickup location

Once the driver accepted the pickup order, your on-demand logistics backend proceeds to work with Trips API to create a trip for the driver to the destination at pickup location and provide a real-time tracking experience to the customer.

Create a trip with destination at pick up location

To create driver tracking experience for the customer, create a trip with ETA to the pickup destination. Once the pickup order is accepted by the driver, inside your on-demand logistics backend, Use Trips API to create a trip for driver.

See the code example below that creates a trip with ETA for driver's device_id, with pickup destination:

// Instantiate Node.js helper library instance
const hypertrack = require('hypertrack')(accountId, secretKey);
let tripData = {
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"destination": {
"geometry": {
"type": "Point",
"coordinates": [35.107479, 47.856564]
}
}
};
hypertrack.trips.create(tripData).then(trip => {
// Trip created
}).catch(error => {
// Error handling
})

Understanding Trips API create trip response

Once the trip is created, the Trips API responds with an active trip object that returns the original payload with additional properties.

You will get an example payload response like the one below. In the response you get estimate (route/ETA) to destination, shareable URL for customers, embed URL for ops dashboards for active ( as noted in status field in the response ) trip.

The destination object in the response will now contain address field which is an address that HyperTrack determines ( reverse geocodes ) based on destination coordinates you submitted in the trips creation request above. You can use this address to show the destination to the user after creating the trip.

HTTP 201 - New trip with destination
{
"trip_id":"2a819f6a-5bee-4192-9077-24fc61503ae9",
"device_id":"00112233-4455-6677-8899-AABBCCDDEEFF",
"started_at":"2020-04-20T00:57:33.484361Z",
"completed_at":null,
"status":"active",
"views":{
"embed_url":"https://embed.hypertrack.com/trips/2a819f6a-5bee-4192-9077-24fc61503ae9?publishable_key=<your_publishable_key>",
"share_url":"https://trck.at/abcdef"
},
"device_info":{
"os_version":"13.3.1",
"sdk_version":"4.0.2-rc.5"
},
"destination":{
"geometry":{
"type":"Point",
"coordinates":[
-122.500005,
37.785334
]
},
"radius":30,
"scheduled_at":null,
"address":"100 34th Ave, San Francisco, CA 94121, USA"
},
"estimate":{
"arrive_at":"2020-04-20T01:06:45.914154Z",
"route":{
"distance":4143,
"duration":552,
"remaining_duration":552,
"start_address":"55 Spear St, San Francisco, CA 94105, USA",
"end_address":"100 34th Ave, San Francisco, CA 94121, USA",
"polyline":{
"type":"LineString",
"coordinates":[
[
-122.50385,
37.76112
],
...
]
}
}
},
"eta_relevance_data":{
"status":true
}
}

Estimate object in Trip API response

The Trips API responds with an active trip object that returns the original payload with additional properties. HyperTrack provides estimates for every trip with a destination.

Since in the API request we specified a destination, the Trips API response will return the estimate object with fields are explained here as follows:

  • Field arrive_at shows estimated time of arrival (ETA) as UTC timestamp
  • Object route contains the following data:
    • Field distance shares estimated route distance (in meters)
    • Fields duration and remaining_duration share actual and remaining durations (in seconds)
    • Fields start_address and end_address display reverse geocoded place names and addresses for trip start, complete and intermediate stops (based on activity)
    • Field polyline contains an array of coordinates for the estimated route from the live location to the destination as polyline in GeoJSON LineString format. It is an array of Point coordinates with each element linked to the next, thus creating a pathway to the destination.
HTTP 201 - New trip with destination
"estimate":{
"arrive_at":"2020-04-20T01:06:45.914154Z",
"route":{
"distance":4143,
"duration":552,
"remaining_duration":552,
"start_address":"55 Spear St, San Francisco, CA 94105, USA",
"end_address":"100 34th Ave, San Francisco, CA 94121, USA",
"polyline":{
"type":"LineString",
"coordinates":[
[
-122.50385,
37.76112
],
...
]
}
}
}
important

Device tracking for your driver's app will be started remotely if you have integrated push notifications with HyperTrack SDK on iOS and Android.

Starting and completing trips would automatically control the start and stop of tracking on the driver's device. This way, your on-demand logistics backend manages device tracking through just one API.

The driver's app would start tracking (unless already tracking) when on-demand logistics backend starts a trip for the device. The device will stop tracking when all active trips for device are completed. HyperTrack uses a combination of silent push notifications and sync method on the SDK to ensure that tracking starts and stops for the device.

Create driver trip tracking experience in customer app

Once the driver accepts the order, your customer app should immediately start showing driver's location with the expected route to the pick up destination and displays ETA in real-time. From the steps above, your on-demand logistics backend created a trip for the driver to the pick up destination. The trip_id for this trip is stored by your on-demand logistics backend and is associated with the order.

Customer app uses Views SDK to receive trip status and real-time updates. Your customer app uses callbacks to receive this data and show them in the customer app.

Please review stream data to native apps guide to understand how this is done for iOS and Android apps using Views SDK. Once you integrate Views SDK with the customer app, the customer will be able to:

  • See driver moving to the pickup destination in real-timel with an expected route
  • Observe route changes as driver diverges from the expected route
  • Observe ETA in real-time
  • Receive delay notifications in the app

Complete trip at the pickup destination

Once the driver meets the customer at the pickup destination, the following takes place:

  • Driver marks the pickup in the driver app
  • On-demand logistics backend sends a request to complete trip with the trip_id for the trip to the pick up destination

Your on-demand logistics backend uses Trips API to complete the trip with trip_id as follows:

In order to complete the trip, HyperTrack provides you Trips complete API. In the response, you will get markers for activity and outages as to capture history of device movement. Completed trips also include a summary with total duration, distance and steps.

POST   https://v3.api.hypertrack.com/trips/{trip_id}/complete

important

Driver app tracking will be stopped since you will have integrated push notifications for your app with HyperTrack SDK on iOS and Android.

Track ongoing order to drop off location

Once the driver picks up the customer at the pickup location, your on-demand logistics backend proceeds to work with Trips API to create a trip for the driver to the drop off destination.

Create a trip with destination at drop off location

Follow steps just as listed in create a trip with destination at pick up location above, with a trip to destination at the drop off location.

Customer app tracking experience for trip to drop off location

The steps above will generate a new trip_id. Using this trip_id your customer app will receive real-time trip updates just as described in the above in create driver trip tracking experience in customer app. You replicate the exact steps to support customer's experience of tracking the trip to the drop off location.

Complete trip at the drop off destination

Once the driver drops off the customer at the drop off destination, the driver marks the order as completed in the app. Once your on-demand logistics backend is notified, it goes ahead to complete active trip with it's trip_id via Trips API just as described for the previous steps above in complete trip at the pickup destination

Share tracking updates

As the driver transports the customer to the drop off destination, you can provide real-time location tracking experience to the customer, customer's family, and friends. This can be done with the share URL link as explained below.

Share URL for trip to drop off location

Trips API gives you an ability for you, as a developer, to create live, real-time, high fidelity, location sharing with your customer via share_url link.

Please see an image below for a mobile location sharing viewing experience in the web browser. This link can be shared with family and friend. Once they receive the link, the web browser will continually display and update the location of the driver's device as it moves towards the drop off destination while ETA is updated live.

Tracking Experience

Share URL has the following structure: https://trck.at/{7_digit_tracking_id}.

This makes it a total of 23 characters, and therefore a friendly URL to share via text or other messengers. Share URLs stay accessible permanently and show trip summary after trip completion.

Generate order summary

Once the oder to the drop off destination is complete, your on-demand logistics backend completes the trip and generates a trip summary that can be shared with both customer and the driver.

A final trip summary view for a trip may look like this:

Tracking Experience

Trip summary data

Once the trip is complete, your on-demand logistics backend can obtain detailed trip summary with distance from the pick up destination to drop off destination, including time spent as an input into your app to calculate billing charges for the customer. Please review to get detailed information on the trip summary data structure.

Architecture review

In summary, your on-demand apps and backend will work with HyperTrack as follows:

Location Map

  1. Request pickup at location X and dropoff to location Y
  2. Get drivers near location X and assign pickup to location X to these drivers
  3. A driver accepts order to location X
  4. In on-demand logistics backend, create trip with destination X via Trips API
  5. Customer tracks driver with ETA to location
  6. Driver picks up customer at location X
  7. In on-demand logistics backend, complete trip with destination X and create trip with destination Y via Trips API
  8. Driver drops off customer at Location Y
  9. Complete trip with destination Y via Trips API via on-demand logistics backend

Ridesharing sample app

This works best for product development teams who are starting to build an app for their business and want to kickstart with an open sourced app built with HyperTrack for ridesharing, gig economy, and on-demand delivery use cases.

HyperTrack provides popular open source ridesharing sample apps for Android and iOS. Clone or fork these sample apps to get started.

      

Questions?

If you would like help with on demand logistics use cases using live location, questions or comments on any of the topics above, please do not hesitate to contact us.

Is this page useful?