Skip to content

Route optimization

With the help of the interface optimize the sequence of several stops can be optimized, either as the fastest or the shortest route.

The consideration of vehicle characteristics, type of transported goods (dangerous goods, etc.), tunnel restrictions as well as desired arrival and stay times for the individual stops is possible. Furthermore, with the Detour-Editor defined rules are included in the optimized route calculation.

If one of the stops is both start and destination, a circular route is calculated. At least one start and one destination must be specified.

Specifying the start time ensures that current (if available in the specified period) and statistical traffic data as well as traffic events (e.g. road works) are included in the route calculation.

optimize interface

Specifying many stops or large routing area affects the duration of route calculation on the server. This means that route optimization takes place in two steps:

In the first step, the stops and other relevant information (vehicle properties, etc.) are transmitted to the server via POST request. The response to this initial request contains an ID that is used in the second step, the subsequent GET request, is used to request the calculated route.

Perform a route optimization

In the following example, the route is to be calculated for four stops. For better comprehensibility, the stops were named according to the expected sequence within the calculated route as First, Second, Third and Fourth.

The specification of the stops in the request is done in an order that is unfavorable in reality and should be ordered accordingly.

This simple example does not take into account all the above possibilities of the interface optimize. The parameters for including vehicle data, desired arrival times, etc. in the calculation can be found in the detailed API documentation.

The list of parameters below is missing the Token,which must be part of all calls to the interface.

Request for the transmission of the stops

POST /optimize/stops

Parameters:

  • provider (String)

    Possible values (pay attention to exact notation):

    • TomTom
    • HERE
    • OpenStreetMap
  • startTime (Date, Time, Time Zone; ISO 8601)

    Start time at which the route will begin. Example: 2021-07-06T17:02:00+02:00

  • stop (Json Body)

    List of stops consisting of

    • the coordinates(Latitude and longitude in WGS84 decimal format - EPSG:4326)
    • a unique name
    • the indication whether it is the start and/or the destination
    • an optional length of stay
    • an optional time window for the scheduled arrival

    In the concrete example:

     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
    [
      {
        "coordinate": {
          "lat": 50.691484858668005,
          "lon": 7.1483925186882855
        },
        "name": "First",
        "start": true
      },
      {
        "coordinate": {
          "lat": 50.69671809152664,
          "lon": 7.141734794677841
        },
        "name": "Third"
      },
      {
        "coordinate": {
          "lat": 50.69395380251723,
          "lon": 7.144616878805644
        },
        "name": "Second"
      },
      {
        "coordinate": {
          "lat": 50.70095415930458,
          "lon": 7.137548935003027
        },
        "name": "Fourth",
        "destination": true
      }
    ]
    

Example curl-command

curl -X POST "https://api.maptrip.de/v1/optimize/stops?provider=TomTom&startTime=2022-01-01T17%3A02%3A00%2B02%3A00&vehicle=car&type=fastest&traffic=false&width=0&height=0&length=0&weight=0&axles=0&axleLoad=0&hazardousGoods=false&explosiveMaterials=false&materialsHarmfulToWater=false&tunnelRestrictionCode=tunnelRestrictionCode_example" -H "accept: application/json" -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ" -H "Content-Type: application/json" -d "[ { \"coordinate\": { \"lat\": 50.691484858668005, \"lon\": 7.1483925186882855 }, \"name\": \"First\", \"start\": true }, { \"coordinate\": { \"lat\": 50.69671809152664, \"lon\": 7.141734794677841 }, \"name\": \"Third\" }, { \"coordinate\": { \"lat\": 50.69395380251723, \"lon\": 7.144616878805644 }, \"name\": \"Second\" }, { \"coordinate\": { \"lat\": 50.70095415930458, \"lon\": 7.137548935003027 }, \"name\": \"Fourth\", \"destination\": true }]"

Response

1
2
3
4
{
  "id": "574265e9-21c7-4a51-90cc-cfa7631e6805",
  "href": "/optimize/stops/574265e9-21c7-4a51-90cc-cfa7631e6805"
}

The id is used in the following GET request to fetch the route.

Request to query the route

The result of the previously triggered route calculation is queried with a GET request.

As for the other requests, the token for authorization is required.

Request

GET /optimize/stops/{id}

URL Placeholder:

  • id (String)

    The query ID supplied in the previously received response..

Example curl-command

curl -X GET "https://api.maptrip.de/v1/optimize/stops/574265e9-21c7-4a51-90cc-cfa7631e6805" -H "accept: application/json" -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJ"

Response

 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
[
  {
    "name": "First",
    "coordinate": {
      "lat": 50.691484858668005,
      "lon": 7.1483925186882855
    },
    "start": true,
    "destination": false
  },
  {
    "name": "Second",
    "coordinate": {
      "lat": 50.69395380251723,
      "lon": 7.144616878805644
    },
    "start": false,
    "destination": false
  },
  {
    "name": "Third",
    "coordinate": {
      "lat": 50.69671809152664,
      "lon": 7.141734794677841
    },
    "start": false,
    "destination": false
  },
  {
    "name": "Fourth",
    "coordinate": {
      "lat": 50.70095415930458,
      "lon": 7.137548935003027
    },
    "start": false,
    "destination": true
  }
]