Route Optimization

With the help of the endpoints [POST] /optimize/stops and [GET] /optimize/stops/{id}, you can optimize the sequence of several stops based on either the fastest or the shortest route.

The optimization process can take into account vehicle characteristics, type of transported goods (eg. dangerous goods), tunnel restrictions as well as desired arrival and stay times for the individual stops. Additionally, rules defined with Detour or the MapTrip Detour Editor are included in the optimized route calculation.

If one of the stops serves as both the starting point and the destination, a circular route is calculated. Exactly one starting point and one destination must be defined.

Note on Asynchronous Use

When specifying a large number of stops or a wide routing area, the server may take longer to calculate the optimized route.
As a result, the route optimization process occurs in two steps:

1. Step 1: Submit the Request
   Send the stops and other relevant information (e.g., vehicle properties) to the server using a POST request.
   The server responds with an ID that uniquely identifies your request.

2. Step 2: Check the Status
   Use the ID from the POST response to send a GET request and check the status of the optimization. If the process is not yet complete, the status is "Running". When the status is "Done", the optimized sequence of stops will be included in your response.

Limitations

The number of stops that can be optimized is limited and 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 this example, a route is calculated for four stops.

To enhance clarity, the stops are named according to the expected order within the optimized route: First, Second, Third, and Fourth.

The stops are specified in a sequence that is intentionally unfavorable, demonstrating how the optimization process rearranges them into the ideal order.

This example does not utilize all the features of the [POST] /optimize/stops endpoint, such as including vehicle data, desired arrival times, or other advanced parameters. Detailed information about these parameters can be found in the 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 is used as start or not
• destination: A boolean which defines if this stop is 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, eg. a warehouse's opening hours

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 one stop marked as start
• There has to be 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. Note, in this example the first stop is marked as start and the last as destination.

 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

[
  {
    "coordinate": {
      "lat": 50.691484858668005,
      "lon": 7.1483925186882855
    },
    "name": "First",
    "start": true
  },
  {
    "coordinate": {
      "lat": 50.69671809152664,
      "lon": 7.141734794677841
    },
    "name": "Third",
    "timeSlots": [
      "begin": "2024-12-23T09:00:00.000Z",
      "end": "2024-12-23T11:00:00.000Z"
    ],
  },
  {
    "coordinate": {
      "lat": 50.69395380251723,
      "lon": 7.144616878805644
    },
    "name": "Second",
    "duration": 15,
  },
  {
    "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&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\", \"timeSlots\": [ { \"begin\": \"2024-12-23T09:00:00.000Z\", \"end\": \"2024-12-23T11:00:00.000Z\" } ] }, { \"coordinate\": { \"lat\": 50.69395380251723, \"lon\": 7.144616878805644 }, \"name\": \"Second\", \"duration\": 15 }, { \"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"
}

Retain the ID for use in the subsequent GET request to retrieve the optimized route.

Request to query the route

The result of the previously triggered optimization request is queried with a GET request using the ID.

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 <token>"

Response

The response depends on whether the optimization process has completed.
1. Status Running
If the optimization is still in progress, the response will included the status "Running". In this case, wait for a while and send the request again later.

1
2
3
4

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

 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
    }
  ]
}