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

In FollowMe it is very important to use the same maps both on the mobile navigation devices and on the server and in the FollowMe Editor. Therefore, the Server-API offers a function to query the list of available map releases. You can then choose the correct release which you are also using on your mobile MapTrip FollowMe installations.

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

The function requires only one input parameter:

  • Map provider (TomTom, HERE or OpenStreetMap)

The response may look something like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
[ 
  { 
    "id": "OSM_Incheon_2019_03", 
    "provider": "OpenStreetMap", 
    "release": "2019.03" 
  }, 
  { 
    "id": "OSM_EU_2020_09", 
    "provider": "OpenStreetMap", 
    "release": "2020.09" 
  }, 
  { 
    "id": "OSM_EU_2021_02", 
    "provider": "OpenStreetMap", 
    "release": "2021.02" 
  } 
]

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

Create a FollowMe Folder

Tracks are organized in folders. With the function 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.

To create a folder, use the function POST 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 meta data about the track and references the geometry file of the track.

  • Date of creation
  • Description
  • Map ID: Version of the map
  • Date of last modification
  • Name

To create a FollowMe file use 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 recoding feature, by the FollowMe editor or by other third party software.

The requirements for the format of the file are:

  • Separator: Semicolon
  • 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;Sammeln Start;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;Hier rückwärts;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

After you have created a FollowMe file it resides on the server, but it is not immediately available on the mobile navigation devices which are running MapTrip. If you want to make a file available on a navigation device, you have to publish it first. (Note: Users may also have to synchronize their MapTrip navigation software in the FollowMe dialog.)

Use the function POST /followme/folder/{folder}/file/{file}/publish/all to publish a FollowMe file to all your devices.

Use the function POST /followme/folder/{folder}/file/{file}/publish/devices to publish a FollowMe file to selected devices.

The publish function is always applied to one 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.

The publish function requires

  • The ID of the folder which contains the file
  • The name of the file that you want to publish
  • A list of the devices’ IDs to which to publish the file (not necessary if /publish/all is used)

In order to query the IDs of your FollowMe devices use the function GET /followme/devices. It will return a list of all your devices which are enabled for the FollowMe feature.

Please note: The publish/device function is interpreted by the Server-API that only the specified device is to have 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 function GET /followme/folder/{folder}/file/{file}/csv/{date}

The function 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 function 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 function 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. GET /followme/folder/{folder}/file/{file}/ride/{ride}/remarks

The function 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 function GET /followme/folder/{folder}/file/{file}/ride/{ride}/status.

The function 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" 
      } 
    } 
  ] 
}