> ## Documentation Index
> Fetch the complete documentation index at: https://maps.solvice.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

The Solvice Maps Distance Matrix service is specifically made for products that use route optimization to power scheduling operations.
Route optimization (TSP, PDP, VRP, ...) requires the usage of a distance matrix detailing the travel time and distance from every location to every other location in the solve request.

## Traffic unaware (OSM)

<Steps>
  <Step title="Send coordinates">
    > POST `/table`

    ```json theme={null}
    {
        "coordinates": [
            [4.912342132, 50.2123123],
            [4.812341234, 50.4123421],
            [5.012341342, 50.9124312],
            [5.057869730, 50.4940923]
        ]
    }
    ```

    ```json theme={null}
    {
        "createdAt": "2025-05-15T12:43:45.756Z",
        "id": 4309631,
        "status": "IN_PROGRESS",
        "tableResponseId": 4309631,
        "updatedAt": "2025-05-15T12:43:45.758Z"
    }
    ```

    <Tip>If you have small matrices and want to integrate a fast synchronous service, use the `/table/sync` endpoint.</Tip>
  </Step>

  <Step title="Poll table until ready">
    > GET `/table/4309631/status`

    ```json theme={null}
    {
        "createdAt": "2025-05-15T12:43:45.756Z",
        "id": 4309631,
        "status": "COMPLETED",
        "tableResponseId": 4309631,
        "updatedAt": "2025-05-15T12:43:46.012Z"
    }
    ```
  </Step>

  <Step title="Get response (gzipped)">
    Make sure you test this endpoint with a browser or  that supports gzip compression.

    > GET `/table/4309631/response`

    ```json [expandable] theme={null}
    {
        "destinations": [
    {
        "hint": "eX5AgduYjYYsAAAAlAAAAHIAAAAAAAAAxBf6QX7HzELIz51CAAAAACwAAACUAAAAcgAAAAAAAAAVtwAAlMNKAIj__QKgxEoAwP39AgEAXwRPrDVe",
        "distance": 54.20808645369059,
        "name": "Avenue de la Restauration",
        "location": [
        4.899732,
        50.200456
        ]
    },
    {
        "hint": "o_v2gPMxk4KXAAAAQwAAAJsAAADWAwAA4YOXQ0HtBEOh05pDGnn1RJcAAABDAAAAmwAAANYDAAAVtwAAEyhJAG0BAQMAPkkAAAsBAwMAXxRPrDVe",
        "distance": 483.4921257061384,
        "name": "Route des Trois Communes",
        "location": [
        4.794387,
        50.397549
        ]
    },
    {
        "hint": "WvwMgrAseoRNAAAAAAAAALwAAAAAAAAAvYZVQgAAAAAK0AFDAAAAAE0AAAAAAAAAvAAAAAAAAAAVtwAAI1ZMAPmtCANAS0wAIKwIAwYAXw9PrDVe",
        "distance": 202.89814553989248,
        "name": "Wittebos",
        "location": [
        5.002787,
        50.900473
        ]
    },
    {
        "hint": "GtVBggTgEIkDAAAADwAAAMUAAAAAAAAAbWKjQHMstUHaEZlDAAAAAAMAAAAPAAAAxQAAAAAAAAAVtwAA-Q5NAN2rCAOQDk0AIKwIAwsAHw5PrDVe",
        "distance": 10.496399718824598,
        "name": "Tiensestraat",
        "location": [
        5.050105,
        50.899933
        ]
    }
        ],
        "durations": [
        [
        0,
        1976.1,
        5772.3,
        5642.6
        ],
        [
        2010.2,
        0,
        4783.9,
        4654.2
        ],
        [
        5817.2,
        4797.4,
        0,
        508.6
        ],
        [
        5705.3,
        4685.5,
        530.2,
        0
        ]
        ],
        "sources": [
    {
        "hint": "eX5AgduYjYYsAAAAlAAAAHIAAAAAAAAAxBf6QX7HzELIz51CAAAAACwAAACUAAAAcgAAAAAAAAAVtwAAlMNKAIj__QKgxEoAwP39AgEAXwRPrDVe",
        "distance": 54.20808645369059,
        "name": "Avenue de la Restauration",
        "location": [
        4.899732,
        50.200456
        ]
    },
    {
        "hint": "o_v2gPMxk4KXAAAAQwAAAJsAAADWAwAA4YOXQ0HtBEOh05pDGnn1RJcAAABDAAAAmwAAANYDAAAVtwAAEyhJAG0BAQMAPkkAAAsBAwMAXxRPrDVe",
        "distance": 483.4921257061384,
        "name": "Route des Trois Communes",
        "location": [
        4.794387,
        50.397549
        ]
    },
    {
        "hint": "WvwMgrAseoRNAAAAAAAAALwAAAAAAAAAvYZVQgAAAAAK0AFDAAAAAE0AAAAAAAAAvAAAAAAAAAAVtwAAI1ZMAPmtCANAS0wAIKwIAwYAXw9PrDVe",
        "distance": 202.89814553989248,
        "name": "Wittebos",
        "location": [
        5.002787,
        50.900473
        ]
    },
    {
        "hint": "GtVBggTgEIkDAAAADwAAAMUAAAAAAAAAbWKjQHMstUHaEZlDAAAAAAMAAAAPAAAAxQAAAAAAAAAVtwAA-Q5NAN2rCAOQDk0AIKwIAwsAHw5PrDVe",
        "distance": 10.496399718824598,
        "name": "Tiensestraat",
        "location": [
        5.050105,
        50.899933
        ]
    }
        ]
    }
    ```

    <Tip>Prefer the signed url approach through the `/table/{id}/response/url` which redirects to Google Cloud Storage over our API.</Tip>
  </Step>
</Steps>

## Traffic aware (TomTom)

Solvice Maps has integrated TomTom road segment information in order to produce Traffic-aware routing. It is based on slices of adjusted travel time information.
To get Traffic aware distance matrices, you need to set the `departureTime` as well as setting the routing `"engine": TOMTOM`.

At Solvice, we use the following slices:

| Period        | From  | To    |
| ------------- | ----- | ----- |
| NIGHT         | 20:30 | 06:30 |
| MORNING\_RUSH | 06:30 | 09:30 |
| MORNING       | 09:30 | 12:00 |
| MIDDAY        | 12:00 | 14:30 |
| AFTERNOON     | 14:30 | 16:30 |
| EVENING\_RUSH | 16:30 | 19:30 |

In between slices, you can get interpolated values by setting the property `"interpolate": true`.
Like so:

> POST `/table`

```json theme={null}
{
    "coordinates": [
        [4.912342132, 50.2123123],
        [4.812341234, 50.4123421],
        [5.012341342, 50.9124312],
        [5.057869730, 50.4940923]
    ],
    "departureTime": "2025-06-25T14:30:00",
    "engine": "TOMTOM",
    "interpolate": true

}
```

```json theme={null}
{
    "createdAt": "2025-05-15T12:43:45.756Z",
    "id": 4309631,
    "status": "IN_PROGRESS",
    "tableResponseId": 4309631,
    "updatedAt": "2025-05-15T12:43:45.758Z"
}
```

## Real-time traffic (TomTom)

For matrices that should reflect *current* traffic conditions, use the `TOMTOM_REAL_TIME` engine on the synchronous `/table/sync` endpoint. Real-time matrices are computed against live road conditions and are not cacheable, so they are sync-only.

> POST `/table/sync`

```json theme={null}
{
    "coordinates": [
        [4.35171, 50.85034],
        [4.40269, 50.83712],
        [4.44216, 50.63650],
        [4.63099, 50.58673]
    ],
    "sources": [0, 1],
    "annotations": ["duration"],
    "engine": "TOMTOM_REAL_TIME"
}
```

With this request, coordinates `0` and `1` are sources and coordinates `2` and `3` are destinations, so the response is a 2 × 2 matrix:

```json theme={null}
{
    "durations": [
        [1875.2, 2654.1],
        [1812.4, 2598.9]
    ]
}
```

### Constraints

* **Endpoint** — `POST /table/sync` only. `TOMTOM_REAL_TIME` is rejected on the async `POST /table` endpoint with HTTP 400.
* **`sources` is required** and must be a contiguous range starting at `0` (e.g. `[0,1,2]`). The first `sources.size` coordinates are sources, the remainder are destinations. The result matrix has shape `sources.size × (coordinates.size − sources.size)` — it is **not** padded to a square matrix.
* **`destinations` is not supported** — leave it out and rely on the `sources` split above.
* **`annotations`** must not include `"distance"`; the upstream provider does not return distances in real-time matrix mode. Use `["duration"]` (or omit the field).
* **`departureTime` is ignored** — every request uses the current time.
* **Billing** is per destination (`coordinates.size − sources.size`), not per matrix cell.