Introduction

The Fleet Connectivity Service is a REST API that allows a fleet dispatcher and the mobile units that make up a fleet (mobile assets, like a delivery vehicle (truck, car, or even bicycle) to communicate.

This communication includes job “allocation”, “acceptance” and “status updates” to enable the management of a fleet. You can use HERE’s Fleet Connectivity Services by using the HERE iOS and Android Premium Edition SDKs.

Below is a quick diagram showing the interaction between the fleet operator and a fleet of mobile assets.

Pre-Reqs.

For this tutorial, you will need

• An account with developer.here.com

Scenario

For this tutorial, we will be simulating a fleet operator to a delivery vehicle communication pipeline.

An “Asset” ( or delivery vehicle) is on the way to deliver some goods. The Dispatcher (or a Fleet Operator Employee) needs to send a “job” (or an Instruction or command) to the Asset. The job is a simple instruction, (“Drive to store A”). The following image shows a swim lane diagram of the communication between the Dispatcher and the Asset.

In this scenario, you see how the Asset provides a status update of “Ready” whereby the Operator sends a job to “Drive to store A”. The Asset responds with an Estimated Time of Arrival (ETA) of 9:35.

Subsequently, the Asset Operator (aka Driver) sends a status update of “Running Late” when they run into traffic.

The Dispatcher subsequently sends a few more “jobs” to the Asset for the next stops.

In this scenario, you can see how a communication infrastructure is needed to make the process run smoothly. HERE’s Fleet Connectivity Services offer a REST API to provide this communication infrastructure.

Fleet Connectivity Services:

The Fleet Connectivity Web Service provides a hub for Operators and Dispatchers to communicate.

There are two modules you can embed into your existing Fleet Management application to help to manage your fleet effectively:

Administrative Module

The Administrative Module is responsible for managing mobile assets in the fleet. The Administrative Module is a REST API that allows the dispatcher(admin) to send jobs to the assets and regularly poll for updates.

In reality, the dispatcher function can make use of one or more physical or logical dispatcher applications with identical functionality and responsibilities to ensure optimal load distribution and fault tolerance. Dispatcher applications can direct and monitor separate or overlapping sets of assets (for example per country or per store).

Asset Module

An asset Module is a client-side application inside an Asset. An Asset represents a mobile unit in a fleet (for example a delivery truck, a car, or a motorcycle) and is capable of running an application created with a HERE iOS and Android Premium Edition SDKs that provides routing services to the asset and interacts with one or more dispatchers via the Fleet Connectivity.

Fleet Connectivity Information Flow

The information exchanged between dispatchers and assets with the help of the Fleet Connectivity indicates jobs to be carried out, status details, and updates.

Job

A job is a message containing a package of information that must include at least the geographic coordinates of the destination but may also include other information depending on the application the asset uses. When a dispatcher sends a job to an asset, the job replaces any previous jobs that were sent to the asset. An empty job without a destination cancels the current destination so that the asset is idle.

Event

An event is a message with information about the status of an asset. It is sent from the asset to the Fleet Connectivity Web Service.

Update

An update is a message from the Fleet Connectivity Web Service sent to the dispatcher with asset status information. An update may contain one or more events that describe a new estimated time of arrival or status information update on a particular job, for example, to indicate whether the job was accepted, canceled, or denied.

Update messages expire after one month regardless of their state, but dispatcher applications should impose a use-case-dependent lower limit on the validity time of an update, usually a few hours. Until a message has expired, the dispatcher can retrieve it as many times as necessary.

Sending a Job to a Mobile Asset

Let’s look at how the API is used in the Admin module. The following sample is an endpoint to send a job to a Mobile Asset.

Note: Before you send this request make sure to replace the YOUR_API_KEY with your API key that can be found in your Developer Account at developer.here.com.

Method: POST

https://fce.ls.hereapi.com/1/sendjob.json?apiKey=YOUR_API_KEY

Body:

Type: JSON

{
  "version" : "1.0",
  "job_id" : "job-1234",
  "dispatcher_id" : "Dispatcher-1",
  "type" : "NEW_DESTINATION",
  "asset_id" : "Vehicle-1",
  "message" :"This is an example job.",
  "content" : {
    "destination" : "52.53086,13.38469",
    "avoidAreas" : "50.145743,8.560077;50.139527,8.571493;",
    "mode" : "fastest,car,traffic:enabled"
   }
}

Once you send the above request, you will receive the following response

{
    "job_id": "job-1234"
}

Requesting Updates from Assets

Now let’s look at the API that is used to get updates from the Asset Module (client-side Driver App). The following is the sample endpoint.

Note: Before you send this request make sure replace the YOUR_API_KEY with your own

Method: GET

https://fce.ls.hereapi.com/1/assetupdate.json?apiKey=YOUR_API_KEY&event={"asset_id":"Asset-1","dispatcher_id":"Dispatcher-1"}

Once you send the above request you will receive the following response:

{
    "jobs": [
        {
            "job_id": "job-1234",
            "dispatcher_id": "Dispatcher-1",
            "creation_time_ms": 1597648875737,
            "asset_id": "Asset-1",
            "type": "NEW_DESTINATION",
            "message": "This is an example job.",
            "version": "1.0",
            "content": {
                "destination": "52.53086,13.38469",
                "avoidAreas": "50.145743,8.560077;50.139527,8.571493;",
                "mode": "fastest,car,traffic:enabled"
            }
        }
    ]
}

Fleet Connectivity Demo

For your convenience we have created a quick demo so you can play around with the Fleet Connectivity APIs. This demo allows you to send, request and poll for jobs. Here is the Fleet Connectivity demo Application where you can experience interacting with both of the above APIs.

Conclusion

After going through the tutorial, you should now have a base level of understanding about what the Fleet Connectivity API is, who will use it and how to use it.

Next steps

Are you a Google Map user? Check our other tutorials:

• Switch from Google to HERE JavaScript Map Routing

• Switch from Google to HERE JavaScript Map Geocoding