FollowMe
FollowMe Navigation Overview
FollowMe is a navigation feature for following pre-defined, complex tours. Rather than calculating routes, FollowMe guides drivers along already specified tracks laid out with exact coordinates.
Common use cases might include:
- Waste collection routes
- Snow plowing or winter road maintenance
- Street cleaning operations
The FollowMe guided navigation system ensures drivers follow specific tours exactly as they are defined.
Map Data Compatibility
Important
For FollowMe navigation to work correctly, the map data must be consistent across all components:
- MapTrip mobile application
- FollowMe Editor
- MapTrip Server API
This includes matching both map data provider (TomTom, HERE, or OpenStreetMap) and release version (e.g., 2023.03)
Retrieving Available Map Releases
If you want too get a list of available map releases, use the following endpoint with a provider
parameter (TomTom, HERE, or OpenStreetMap):
GET /followme/maps
The response includes:
id
: Unique identifier required for creating FollowMe filesprovider
: Map data provider namerelease
: Version of the map data
Example Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
|
When creating FollowMe files, use the id
that matches the map release installed in your MapTrip application.
Create a FollowMe Folder
FollowMe organizes pre-defined tours (tracks) into folders. Each folder has a unique ID that you'll need when creating FollowMe files.
FollowMe Editor Compatibility
The FollowMe Editor currently has limited folder support. If you use both the MapTrip Server API and FollowMe Editor, create files only in the top-level folder. Do not create subfolders through the API. This ensures proper synchronization between both tools.
If you want to retrieve a list of all of the folders in your account in order to quickly retrieve their id
, use the endpoint:
GET /followme/folder
To create a new subfolder, use the endpoint with the new folder name:
POST /followme/folder/{folder}
After creating a folder, you can proceed to create FollowMe files containing your tour data.
Creating and Publishing FollowMe Files
Overview
Getting a tour to your drivers involves three steps:
- Create a new FollowMe file
- Add track data to the file
- Publish the file to MapTrip-enabled navigation devices
Creating a FollowMe File
Use POST followme/folder/{folder}/file
to create a file with the following metadata in the body of the request:
name
: File namedescription
: File descriptionmap
: Map data release IDcreation
: Creation datemodification
: Last modification date
Adding a Track to the File
The track is a sequence of coordinates that are stored in a CSV file and represent the tour the driver will follow. The track can be created by a GPS logger, by using MapTrip’s recording feature, by the FollowMe editor or by other third party software.
The requirements for the format of the file are:
- Separator: Semicolon
- First line has to contain column names
- Coordinates: WGS 84 decimal degree (EPSG:4326)
- Valid names for coordinate columns:
- lat, lon
- lat, long
- latitude, longitude
- xpos, ypos
- Additional columns can be present
Here is an example file:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
|
In order to add a track to your recently created file, you will need the folder's id
and the name
of your file. To add a track to an existing FollowMe file, use the endpoint [POST] /followme/folder/{folder}/file/{file}/csv
with the CSV content included in the body
Publishing a FollowMe File to a Navigation Device
After creating a FollowMe file on the server using the API, you need to publish it to make the tour available to your drivers' navigation devices. Once published, drivers can follow the predefined tour using their MapTrip application.
Publishing a file requires
- The ID of the folder which contains the file
- The name of the file you want to publish
- A list of device IDs to publish the file to (not needed for
[POST] /followme/folder/{folder}/file/{file}/publish/all
)
In order to query the IDs of your FollowMe devices, use the endpoint [GET] /followme/devices
. It will return a list of all your devices which are configured for FollowMe.
To publish the tour to all devices, use the endpoint:
[POST] /followme/folder/{folder}/file/{file}/publish/all
To send the tour to only a certain device or devices, use the endpoint:
[POST] /followme/folder/{folder}/file/{file}/publish/devices
Important: Access Control Behavior
Publishing a file to a device means that only the specified device has access to the specified file. For example: Publish a file A to two devices 1 and 2. Next publish the same file A only to device 1. The file will then be deleted from device 2.
Publishing Limitations
You cannot publish a folder or all your files at once (bulk publishing). The folder structure on the server will be recreated on the mobile devices for the files published.
Other Useful FollowMe Functions
Get track Version History
Tracks often evolve to meet changing needs or for better optimization. For documentation purposes, it may be useful to retrieve previous versions of a FollowMe track as it was driven at an earlier date.
To retrieve previous versions of a track, use the endpoint [GET] /followme/folder/{folder}/file/{file}/csv/{date}
.
The endpoint requires the following input parameters:
- ID of the folder
- Name of the FollowMe file
- Date of the ride (when the track was driven)
Tip: You can query the date of the ride by using the endpoint [GET] /followme/folder/{folder}/file/{file}
.
Get Information About Rides
What are Rides?
Each time a FollowMe tour is driven, a new ride is automatically created on the server. Remarks and status information can be associated to each ride.
To query which rides exist for a FollowMe file, you can query the existing rides by using the endpoint [GET] /followme/folder/{folder}/file/{file}
.
A ride contains the following attributes:
- Date of the ride
- Device ID that drove the ride
- ID of the ride
- Remarks: true/false (are remarks available for this ride?)
Get Remarks of a Ride
A remark is a set of notes drivers can save in MapTrip while following a FollowMe tour. It can be used to collect geo-localized feedback from drivers.
To query the remarks for a specific ride, use the endpoint [GET] /followme/folder/{folder}/file/{file}/ride/{ride}/remarks
.
It expects the following parameters:
- ID of the folder that contains the FollowMe file
- The name of the FollowMe file
- ID of the ride
The response may look like this:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
|
The geometry
of this feature indicates the location where the driver entered this remark. The properties
contain the time as well as the remark TEXT
.
Get the Status of a Ride
The status of a ride will tell you important information such as sections that were missed or discarded. The ride will have one or more of the following parts:
- done
- todo
- missed
- discarded
As conveyed by their names, sections might be missed or discarded by a driver. Query the remarks of the ride to see if there are any notes about why.
To get the status of a ride, use the endpoint [GET] /followme/folder/{folder}/file/{file}/ride/{ride}/status
.
It requires the following parameters:
- ID of the folder that contains the FollowMe file
- Name of the FollowMe file
- ID of the ride
The response may look like this:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 |
|