Route optimization

With the help of the endpoints [POST] /optimize/stops and [GET] /optimize/stops/{id} 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, rules defined with Detour or the MapTrip Detour Editor 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.

Note on asynchronous use

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 uniquely identifies this request. This ID is used in the second step, the subsequent GET request, to request the optimized sequence of stops. If the process is not yet complete, the status is "Running". Only when the status is "Done", you get the optimized sequence.

Limitations

The maximum number of stops is limited. It depends on the size of the region where the coordinates are located. In a small region, a larger amount of stops can be optimized than in a large region.

We distinguish between these regions:

• small: maximum 150 km diameter
• medium: maximum 400 km diameter
• large: maximum 1200 km diameter

The maximum number of stops is set as follows:

If these limitations are not suitable for your use case, please contact our sales team.

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 endpoint [POST] /optimize/stops. 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 endpoint.

Request to [POST] /optimize/stops

Parameters:

• provider: The map data provider (one of TomTom, HERE, or OpenStreetMap)
• startTime: An ISO 8601 string with date, time, and time zone, e.g. 2021-07-06T17:02:00+02:00

The request body is an array of the stops. Every stop can have these properties:

• name: A unique name for this stop (required)
• coordinate: The coordinate of this stop (required)
• start: A boolean which defines if this stop may be used as start or not
• destination: A boolean which defines if this stop may be used as destination or not
• duration: The stay at this stop in minutes
• timeSlots: An array of time slots which define when this stop has to be reached

The stops have to meet these conditions:

• There have to be at least two stops
• The names of the stops have to be unique
• There has to be at least one stop marked as start
• There has to be at least one stop marked as destination
• Stops marked as start must not have time slots
• The begin of a time slot must not be after the end of it
• The begin of a time slot must not be before the start of the tour

Here is an example of a tour consisting of four stops.

 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 <token>" -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 optimization is queried with a GET request.

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

Request to [GET] /optimize/stops/{id}

URL parameters:

• 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

The response depends on whether the optimization has already been completed. If this is not yet the case, you will receive the status "Running".

1
2
3
4

{
  "id": "574265e9-21c7-4a51-90cc-cfa7631e6805",
  "status": "Running"
}

In this case, you will have to wait and resubmit the request later. If the status is "Done", the response contains the optimized sequence of stops:

 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

{
  "id": "574265e9-21c7-4a51-90cc-cfa7631e6805",
  "status": "Done",
  "stops": [
    {
      "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
    }
  ]
}