Distance Matrix

Definition

A distance matrix is a table that gives the distances between several places, for example between several cities:

These matrices also contain travel time and serve as a basis for optimization.

In this case, all cities are used as both the start and the destination - this is called a symmetric matrix. This does not have to be the case, but starts (the rows of the matrix) and destinations (the columns of the matrix) can be specified separately. Imagine, for example, that you want to reach one of several possible destinations from your location: The matrix then consists of one row with several columns:

Synchronous vs. Asynchronous Requests

Matrix calculations can be called both synchronously and asynchronously. In synchronous calls, the server waits until the result is calculated and returns it:

Asynchronous calls start a job on the server and return an ID. You can use this ID to retrieve the result later. If the calculation is not yet complete, the server responds with the status Running:

Limitations

The maximum matrix size is limited. It results from the product of the starts (rows) and destinations (columns) of the matrix:

• For 1 start and 20 destinations the size is 1 x 20 = 20
• For 100 starts and 100 destinations the size is 100 x 100 = 10000

The maximum size depends on the call (synchronous or asynchronous) and on the size of the region where the coordinates are located. In a small region, a larger matrix can be calculated 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 elements (rows x columns) is set as follows:

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

Synchronous Call

Used for small areas with few stops.

The most important input is a list of stops, each consisting of a coordinate, a name, and whether the stop is a start or a destination or both.

Besides the stops, most of the parameters allowed in Routing can be used: You can specify the data provider, the start time (important for both live and statistical traffic situation), the type of route (fastest or shortest route), the type of vehicle to use (car, truck), the vehicle attributes (weight, width, height etc.) and a Detour profile.

Request to [POST] /matrix/sync

In the following example 4 stops in Cologne and surroundings are used. The matrix consists of car routes without traffic information.

Example curl command:

curl -X POST "https://api.maptrip.de/v1/matrix/sync?provider=TomTom&startTime=2021-07-06T17%3A02%3A00%2B02%3A00&vehicle=car&type=fastest" -H "accept: application/json" -H "Authorization: Bearer <token>" -H "Content-Type: application/json" -d "[ { \"coordinate\": { \"lat\": 50.97267, \"lon\": 6.954858 }, \"name\": \"Köln Niehl\", \"start\": true, \"destination\": true },\t{ \"coordinate\": { \"lat\": 50.919199, \"lon\": 6.933562 }, \"name\": \"Köln Sülz\", \"start\": true, \"destination\": true },\t{ \"coordinate\": { \"lat\": 50.927852, \"lon\": 7.016444 }, \"name\": \"Köln Kalk\", \"start\": true, \"destination\": true },\t{ \"coordinate\": { \"lat\": 51.033749, \"lon\": 6.987287 }, \"name\": \"Leverkusen\", \"start\": true, \"destination\": true }]"

Response

The status Done indicates that the calculation of the matrix was successful (otherwise it would be Failed). The list entries contains the routes of the matrix: from and to correspond to the names of the stops, the other values indicate distance (in meters) and travel time (in seconds).

  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
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101

{
  "status": "Done",
  "entries": [
    {
      "from": "Köln Niehl",
      "to": "Köln Niehl",
      "drivingTime": 0,
      "length": 0
    },
    {
      "from": "Köln Niehl",
      "to": "Köln Sülz",
      "drivingTime": 1244,
      "length": 8579
    },
    {
      "from": "Köln Niehl",
      "to": "Köln Kalk",
      "drivingTime": 1251,
      "length": 9138
    },
    {
      "from": "Köln Niehl",
      "to": "Leverkusen",
      "drivingTime": 1328,
      "length": 13785
    },
    {
      "from": "Köln Sülz",
      "to": "Köln Niehl",
      "drivingTime": 1321,
      "length": 8980
    },
    {
      "from": "Köln Sülz",
      "to": "Köln Sülz",
      "drivingTime": 0,
      "length": 0
    },
    {
      "from": "Köln Sülz",
      "to": "Köln Kalk",
      "drivingTime": 902,
      "length": 7837
    },
    {
      "from": "Köln Sülz",
      "to": "Leverkusen",
      "drivingTime": 1885,
      "length": 21329
    },
    {
      "from": "Köln Kalk",
      "to": "Köln Niehl",
      "drivingTime": 1341,
      "length": 9378
    },
    {
      "from": "Köln Kalk",
      "to": "Köln Sülz",
      "drivingTime": 1100,
      "length": 8545
    },
    {
      "from": "Köln Kalk",
      "to": "Köln Kalk",
      "drivingTime": 0,
      "length": 0
    },
    {
      "from": "Köln Kalk",
      "to": "Leverkusen",
      "drivingTime": 1549,
      "length": 16070
    },
    {
      "from": "Leverkusen",
      "to": "Köln Niehl",
      "drivingTime": 1319,
      "length": 13966
    },
    {
      "from": "Leverkusen",
      "to": "Köln Sülz",
      "drivingTime": 1824,
      "length": 21945
    },
    {
      "from": "Leverkusen",
      "to": "Köln Kalk",
      "drivingTime": 1355,
      "length": 20528
    },
    {
      "from": "Leverkusen",
      "to": "Leverkusen",
      "drivingTime": 0,
      "length": 0
    }
  ]
}

Asynchronous Call

Used for large areas or lots of stops.

Request to [POST] /matrix/async

Let's have a look at the same example as above, but with truck routes with some vehicle attributes:

Example curl command:

curl -X POST "https://api.maptrip.de/v1/matrix/async?provider=TomTom&startTime=2021-07-06T17%3A02%3A00%2B02%3A00&vehicle=truck&type=fastest&width=2.5&weight=25000" -H "accept: application/json" -H "Authorization: Bearer <token>" -H "Content-Type: application/json" -d "[ { \"coordinate\": { \"lat\": 50.97267, \"lon\": 6.954858 }, \"name\": \"Köln Niehl\", \"start\": true, \"destination\": true },\t{ \"coordinate\": { \"lat\": 50.919199, \"lon\": 6.933562 }, \"name\": \"Köln Sülz\", \"start\": true, \"destination\": true },\t{ \"coordinate\": { \"lat\": 50.927852, \"lon\": 7.016444 }, \"name\": \"Köln Kalk\", \"start\": true, \"destination\": true },\t{ \"coordinate\": { \"lat\": 51.033749, \"lon\": 6.987287 }, \"name\": \"Leverkusen\", \"start\": true, \"destination\": true }]"

Response

This asynchronous call does not return the matrix but an ID for a matrix calculation job:

1
2
3
4

{
  "id": "e79e5b56-89b5-4bfe-96c7-58771f8302f6",
  "href": "/matrix/e79e5b56-89b5-4bfe-96c7-58771f8302f6"
}

Request to [GET] /matrix/async/{id}

This ID can be used to fetch the matrix:

Example curl command:

curl -X GET "https://api.maptrip.de/v1/matrix/async/e79e5b56-89b5-4bfe-96c7-58771f8302f6" -H "accept: application/json" -H "Authorization: Bearer <token>"

Response

Running this GET request immediately after the POST request will not return the matrix as the calculation is still running. In this case the status will be Running:

1
2
3
4

{
  "id": "e79e5b56-89b5-4bfe-96c7-58771f8302f6",
  "status": "Running"
}

After the calculation is finished the result looks like in the synchronous call.