MapTrip Remote

MapTrip Remote allows you to query the status of all your MapTrip installations, e.g. the current location, destination, estimated time of arrival and more. In addition, you can send new destinations to devices - either a list of coordinates (optionally with via points) or a reference route planned with the MapTrip Server API.

Basics

There is no direct communication between the MapTrip Server API and the device, i.e. you do not send push messages. Instead, both sides communicate with the backend and leave messages there. Therefore, it may take several minutes for a destination sent via the API to show up in MapTrip.

This is shown in the following diagram. In the first phase it shows a routing started from MapTrip. After that you can see a request for the status via the API. In the last phase, a new destination is sent to MapTrip via the API.

Querying Device IDs

The MapTrip Remote endpoints can be used with all devices configured for MapTrip Remote in the MapTrip Manager. This endpoint returns a list of all configured devices.

Request to [GET] /remote/devices

This endpoint returns a list of device IDs.

Example curl command:

curl -X GET "https://api.maptrip.de/v1/remote/devices" -H "accept: application/json" -H "Authorization: Bearer <token>"

Response

1
2
3

[
  "84a265b7-f31f-4402-993f-ba2e279ac28a"
]

Request to [GET] /remote/devices/details

Since a name is easier to remember than an ID, you can also query a list of details about the devices that have been set in the MapTrip Manager.

Example curl command:

curl -X GET "https://api.maptrip.de/v1/remote/devices/details" -H "accept: application/json" -H "Authorization: Bearer <token>"

Response

1
2
3
4
5
6
7
8

[
  {
    "id": "84a265b7-f31f-4402-993f-ba2e279ac28a",
    "name": "My Android smartphone",
    "imei": "123456789012345",
    "notes": "Notes on this device"
  }
]

Setting the Name and Notes of a Device

A device is uniquely identified by its ID, but to make it easier to find in the list of your devices you should use a descriptive name and maybe some notes. These can be set with two endpoints: [PUT] /remote/name/{device} renames a device and [PUT] /remote/notes/{device} sets notes for a device.

Both endpoints have to be called with the ID of one of your devices and the name or notes as plain text in the body. This call sets the name of the device with the ID 84a265b7-f31f-4402-993f-ba2e279ac28a to My smartphone:

curl -X "PUT" "https://api.maptrip.de/v1/remote/name/84a265b7-f31f-4402-993f-ba2e279ac28a" -H "accept: */*" -H "Authorization: Bearer <token>" -H "Content-Type: text/plain" -d "My smartphone"

This call sets the notes of the same device to Description of my smartphone:

curl -X "PUT" "https://api.maptrip.de/v1/remote/notes/84a265b7-f31f-4402-993f-ba2e279ac28a" -H "accept: */*" -H "Authorization: Bearer <token>" -H "Content-Type: text/plain" -d "Description of my smartphone"

Both endpoints will respond to a successful call with the HTTP status code 204 NO CONTENT. See the response of the endpoint GET /remote/devices/details to check the results:

1
2
3
4
5
6
7
8

[
  {
    "id": "84a265b7-f31f-4402-993f-ba2e279ac28a",
    "name": "My smartphone",
    "imei": "123456789012345",
    "notes": "Description of my smartphone"
  }
]

Querying the Status of a Device

MapTrip Remote allows you to query the status of all your MapTrip installations. This includes:

• The current status (active, following a route or inactive)
• The current location of the device
• The current driving direction of the device in degrees
• The destination, distance and estimated time of arrival (if MapTrip is following a route)
• The ID, application, version and operating system of the device

Keep in mind this is the last known status of the device, i.e. the last contact between the device and the backend. Check the property lastContact (in seconds) to find out if the information is up to date.

Request to [GET] /remote/status/{device}

Example curl command:

curl -X GET "https://api.maptrip.de/v1/remote/status/84a265b7-f31f-4402-993f-ba2e279ac28a" -H "accept: application/json" -H "Authorization: Bearer <token>"

Response

Let's have a look at a device on a route from Bonn to Essen with a distance of 87 km and 103 minutes to go. Here is a screenshot (which was done 5 minutes later):

The status looks like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

{
  "id": "84a265b7-f31f-4402-993f-ba2e279ac28a",
  "status": "FollowingRoute",
  "location": {
    "lat": 50.81167740715811,
    "lon": 6.9849493063525925
  },
  "direction": 17,
  "destination": {
    "lat": 51.457910414780805,
    "lon": 7.0138660753484
  },
  "timeToDestination": 6203,
  "distanceToDestination": 86839,
  "app": "de.infoware.maptrip.navi.license",
  "version": "9.2.0.04119478e4",
  "plattform": "Android",
  "lastContact": 56
}

Querying the current Route of a Device

If a device is following a route right now (in this case there is a destination coordinate in the status), you can also query the route. The response format is the same as for the Routing API, i.e. a summary with distance and estimated time of arrival, the driving directions and the route geometry as a GeoJSON object.

Request to [GET] /remote/route/{device}

Example curl command:

curl -X GET "https://api.maptrip.de/v1/remote/route/84a265b7-f31f-4402-993f-ba2e279ac28a" -H "accept: application/json" -H "Authorization: Bearer <token>"

Response

See the Routing API.

Sending a new Itinerary to a Device

The endpoint lets you:

• send a new destination to a device running MapTrip
• Send several destinations that are approached in the specified order
• use via points to determine which route is chosen to a destination

The itinerary is a either a list of coordinates or a list of addresses. In the second case, each address must have a coordinate - street, house number, postal code and city are used only for display in MapTrip.

Each coordinate can optionally have a radius. In this case, it is called a via point, which is not approached as a destination, but determines the route.

An Itinerary of Coordinates

Request to [POST] /remote/route/itinerary/{device}

In this example, we want to calculate a route to Hamburg that goes via Hannover. The highway is not to be left at Hannover, so it is a via point with a radius of 20 km.

The itinerary looks like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

{
  "coordinates": [
    {
      "lat": 52.37790,
      "lon": 9.741819,
      "radius": 20000
    },
    {
      "lat": 53.54461,
      "lon":  9.99690
    }
  ],
  "message": "Hamburg via Hannover"
}

Please note the properties in the highlighted lines which define a radius of 20 km for the first coordinate, and a message that will be displayed to the driver in MapTrip.

Example curl command:

curl -X POST "https://api.maptrip.de/v1/remote/route/itinerary/84a265b7-f31f-4402-993f-ba2e279ac28a" -H "accept: */*" -H "Authorization: Bearer <token>" -H "Content-Type: application/json" -d "{ \"coordinates\": [ { \"lat\": 52.37790, \"lon\": 9.741819, \"radius\": 20000 }, { \"lat\": 53.54461, \"lon\": 9.99690, \"name\": \"Hamburg\" } ], \"message\": \"Hamburg via Hannover\"}"

Response

There is no content for this request. For a successful request the status code is 200 OK.

An Itinerary of Addresses

Request to [POST] /remote/route/itinerary/{device}

Instead of passing coordinates as in the previous example, you can also use addresses. These must have a coordinate, e.g. like the results of the endpoints of the Geocoder API.

In this example the address was geocoded from the string "Bonn Weiherstr 38". The properties part, ags and country can be provided, but are not used. We have removed them from this example and added a name instead.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

{
  "addresses": [
    {
      "name": "infoware GmbH",
      "city": "Bonn",
      "zipcode": "53111",
      "street": "Weiherstr.",
      "housenumber": "38",
      "coordinate": {
        "lat": 50.7365574,
        "lon": 7.0919497
      }
    }
  ],
  "message": "New destination: infoware GmbH"
}

Example curl command:

curl -X POST "http://api.maptrip.de/v1/remote/route/itinerary/84a265b7-f31f-4402-993f-ba2e279ac28a" -H "accept: */*" -H "Authorization: Bearer <token>" -H "Content-Type: application/json" -d "{ \"addresses\": [ { \"city\": \"Bonn\", \"name\": \"infoware GmbH\", \"zipcode\": \"53111\", \"street\": \"Weiherstr.\", \"housenumber\": \"38\", \"coordinate\": { \"lat\": 50.7365574, \"lon\": 7.0919497 } } ], \"message\": \"New destination: infoware GmbH\"}"

Response

There is no content for this request. For a successful request the status code is 200 OK.

These screenshots show the message that there is a new destination for MapTrip and the details of the destination:

Sending a Reference Route to a Device

Reference routes allow you to precalculate a route and pass the coordinates to MapTrip as CSV. The navigation will follow exactly this course of the route.

You can use the optional parameter doGuideThroughStartingPoint to determine if the route from the current position should lead to the starting point of the reference route or to the nearest connection to the reference route (default is false, i.e. nearest connection).

The CSV has to contain at least two columns with latitude and longitude as WGS84 decimal degrees (EPSG:4326). A reference route can be created with the endpoint [GET] /route/reference and looks like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

lat;lon
50.7327;7.09629
50.7328;7.09591
50.73291;7.09552
50.73304;7.09514
50.73317;7.09478
50.73331;7.09441
50.73343;7.09403
50.73354;7.09364
50.73365;7.09325
50.73368;7.09283
50.73372;7.09241
50.73383;7.09202
50.73395;7.09164
50.73408;7.09127
50.73421;7.09089

Request to [POST] /remote/route/reference/{device}

Example curl command:

curl -X POST "https://api.maptrip.de/v1/remote/route/reference/84a265b7-f31f-4402-993f-ba2e279ac28a" -H "accept: */*" -H "Authorization: Bearer <token>" -H "Content-Type: text/csv" -d "lat;lon\n50.7327;7.09629\n50.7328;7.09591\n50.73291;7.09552\n50.73304;7.09514\n50.73317;7.09478\n50.73331;7.09441\n50.73343;7.09403\n50.73354;7.09364\n50.73365;7.09325\n50.73368;7.09283\n50.73372;7.09241\n50.73383;7.09202\n50.73395;7.09164\n50.73408;7.09127\n50.73421;7.09089"

Response

There is no content for this request. For a successful request the status code is 200 OK.