Skip to content

FollowMe

Basics about FollowMe

FollowMe is a navigation feature for driving very complex, externally specified routes. FollowMe navigation does not calculate the routes itself, but supports the driver in following already defined routes. Typical areas of application for FollowMe are household waste collection, winter service or street cleaning.

Choosing the right Maps

Your MapTrip devices and the files you create with the FollowMe Editor and the MapTrip Server API have to use the same map data. Both the map data provider (TomTom, HERE or OpenStreetmap) and the Release (e.g. 2023.03) have to match. Therefore, the Server API offers an endpoint to query the list of available map releases.

Every map data release has an unique ID. Pick the release you are using in MapTrip from the list and use the ID of the map data release for your FollowMe files.

Use [GET] /followme/maps to get a list of all available map releases.

The only parameter of the endpoint is provider (TomTom, HERE or OpenStreetMap).

The response looks like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
[ 
  {
    "id": "TomTom_PLANET_2022_09",
    "provider": "TomTom",
    "release": "2022.09"
  },
  {
    "id": "TomTom_PLANET_2022_12",
    "provider": "TomTom",
    "release": "2022.12"
  },
  {
    "id": "TomTom_PLANET_2023_01",
    "provider": "TomTom",
    "release": "2023.03"
  }
]

The map ID must be specified when creating a FollowMe file.

Create a FollowMe Folder

Tracks are organized in folders. With the endpoint [GET] /followme/folder you can retrieve a list of all existing folders in your account. It also gives you the folder ID, which you will need further below to create a FollowMe file.

Important

Folders are not fully supported in the FollowMe Editor yet. When you want to want to use both the MapTrip Server API and the FollowMe Editor, you should not create sub folders.

To create a folder, use the endpoint [POST] /followme/folder/{folder}.

Next, you can create a FollowMe file which contains the actual track.

Create a FollowMe File

First, the FollowMe file needs to be created. After that the track for the vehicle to follow, can be uploaded separately.

The FollowMe file contains some meta data:

  • name: The Name of the file
  • description: A textual description
  • map: The ID of the release of the map data used in this file
  • creation: Date of creation
  • modification: Date of last modification

To create a FollowMe file use the endpoint [POST] followme/folder/{folder}/file.

Add a Track to a FollowMe File

The track is a sequence of coordinates that are stored in a CSV file. 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
HEADING;SPEED;EVT_TYPE;EVT_DESCR;lon;lat
291.7;0.0;65538;Start collecting;7.140295;50.683959
291.7;0.0;;;7.140295;50.683959
291.7;0.0;;;7.140295;50.683959
291.7;0.7;;;7.140295;50.683965
291.7;0.0;;;7.140295;50.683965
291.7;0.9;;;7.140286;50.683965
291.7;1.9;;;7.140286;50.683965
304.1;10.0;;;7.14025;50.683976
304.9;10.7;;;7.140223;50.683988
310.6;9.6;1;Backwards here;7.140187;50.684005
322.6;8.5;;;7.140169;50.684016
330.9;8.7;;;7.140151;50.684033
0.1;9.8;;;7.140142;50.684056

The track represents the route along which the navigation will eventually guide the driver. The track needs to be added to an existing FollowMe file by using [POST] /followme/folder/{folder}/file/{file}/csv with the CSV content posted as the request body.

Publish a FollowMe File to a Navigation Device

Once you have created a FollowMe file, it is on the server, but it is not immediately available on the mobile navigation devices on which MapTrip is running. If you want to make a file available on a navigation device, you have to publish it.

Use the endpoint [POST] /followme/folder/{folder}/file/{file}/publish/all to publish a FollowMe file to all your devices, or [POST] /followme/folder/{folder}/file/{file}/publish/devices to publish a FollowMe file to selected devices.

Using one of these endpoints will publish a the specified file. You cannot publish a folder or all your files at once. However, the folder structure on the server will be recreated on the mobile devices for the files published.

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.

Important

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

Get the Track That was Driven on a Given Date

A track may evolve and change over time. It is being improved and modified to reflect the changing requirements of the driving task. For documentation purposes, it may be relevant to pull up a FollowMe track as it was driven at an earlier date.

To query previous versions of tracks from an earlier date 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)

Note: You can query the date of the ride by using the endpoint [GET] /followme/folder/{folder}/file/{file}.

What are Rides?

Each time a FollowMe track is driven, a new Ride is automatically created on the server. Remarks and status information can be associated to each Ride.

Get Remarks of a Ride

A remark is a set of notes drivers can save in MapTrip while following a FollowMe track. It can be used to collect geo localized feedback from drivers. Remarks are stored in a Ride.

First, you need to know which Rides exist for the FollowMe track in question. 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?)

Now, you can query the remarks for a specific ride with 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
{ 
  "type": "FeatureCollection", 
  "features": [ 
    { 
      "type": "Feature", 
      "id": 1,
      "geometry": { 
        "type": "Point", 
        "coordinates": [ 
          7.143457,
          50.701395
        ] 
      }, 
      "properties": { 
        "UTC_TIME": "1633336992", 
        "TEXT": "Too many trashcans",
        "CODE": "1" 
      } 
    } 
  ] 
}

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 contains information on which section of the FollowMe track was covered and how much was not driven on (missed). For example: A snow plow is supposed to drive a predefined track. After it has returned you want to check how much of the track was actually cleared from snow and much of the track was not driven on at all. This information is returned by 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
{ 
  "type": "FeatureCollection", 
  "features": [ 
    { 
      "type": "Feature", 
      "id": 1, 
      "geometry": { 
        "type": "LineString", 
        "coordinates": [ 
          [ 
            7.151865, 
            50.695609 
          ], 
          [ 
            7.153572,
            50.69554 
          ] 
        ] 
      }, 
      "properties": { 
        "TYPE": "done", 
        "FROM": "0", 
        "TO": "2812"
      } 
    }, 
    { 
      "type": "Feature", 
      "id": 2, 
      "geometry": { 
        "type": "LineString", 
        "coordinates": [ 
          [ 
            7.14193, 
            50.705309 
          ], 
          [ 
            7.141112, 
            50.704974 
          ] 
        ] 
      }, 
      "properties": { 
        "TYPE": "missed", 
        "FROM": "2812", 
        "TO": "5121" 
      } 
    }, 
    { 
      "type": "Feature", 
      "id": 3, 
      "geometry": { 
        "type": "Point", 
        "coordinates": [ 
          7.153401, 
          50.695546 
        ] 
      }, 
      "properties": { 
        "STATE": "finished",
        "POSITION": "2800", 
        "LENGTH": "5121" 
      } 
    } 
  ] 
}