# Matrix
Source: https://maps.vietmap.vn/docs/map-api/matrix-version/matrix-v4/
Matrix
======
* * *
Matrix v4 returns travel time (seconds) or distance (meters) for every origin → destination pair in one call, instead of N×M Route calls. The response is numbers only — no geometry. Pick origins with `sources`, destinations with `destinations`, and the value type with `annotation`.
Use it to pick the nearest driver or store for a customer (a 1×N matrix), or to build the N×N cost matrix your own routing solver needs. To order stops use [TSP v4](https://maps.vietmap.vn/docs/map-api/tsp-version/tsp-v4/); to split stops across vehicles use [VRP](https://maps.vietmap.vn/docs/map-api/vrp/).
### Playground
!!! tip "Try it in the Playground"
Call Matrix v4 with real data, no code required: **[Open Playground](https://tools.vietmap.vn/playground/matrix)**
!!! tip "AI Agent Integration :sparkles: NEW"
Download the optimized doc for AI agent integration (Matrix + TSP + VRP): **Logistics Agent Doc** · Machine-readable schema: **[OpenAPI 3.1](/docs/openapi.json)**
Or try it in [Postman](https://app.getpostman.com/run-collection/10912981-433d17b2-76d7-416e-beb2-468b9682b7a7?action=collection%2Ffork).
### URL
```
https://maps.vietmap.vn/api/matrix/v4?apikey={your-apikey}&point={point}&point={point}&point={point}&points_encoded={points_encoded}&vehicle={vehicle}&sources={sources}&destinations={destinations}&annotation={annotation}
```
## Method
**GET**
### Migrate from the previous version (short)
- The endpoint changes from `/api/matrix?api-version=1.1` to `/api/matrix/v4` (the `api-version` query parameter is no longer used).
- Matrix v4 runs on the same v4 routing engine as [Route v4](https://maps.vietmap.vn/docs/map-api/route-version/route-v4/), so results are consistent with v4 routes.
- The request parameters and the response format are unchanged, so migrating is a matter of updating the URL.
See the previous version docs: [Deprecated Matrix](https://maps.vietmap.vn/docs/map-api/matrix/).
## Parameters
|Parameter|Type|Required|Default|Description|
|--- |--- |--- |--- |--- |
|apikey|string|yes|none|API key provided by VIETMAP for your account. [Register here](https://maps.vietmap.vn/console-v2/register)|
|point|array string|yes|none|The points for which the route should be calculated. Format: [latitude,longitude]. Specify at least an origin and a destination. Via points are possible. The maximum number depends on your plan.|
|points_encoded|boolean|no|true|Allows changing the encoding of location data in the response. The default is polyline encoding, which is compact but requires special client code to unpack. Set this parameter to false to switch the encoding to simple coordinate pairs like [lon,lat]. See the description of the response format for more information.|
|vehicle|string|no|car|Enum: `car`, `motorcycle`, `truck`, `container`. The vehicle profile for which the matrix should be calculated.|
|sources|int or string|no|all|Zero-based indices of the points to use as origins, in the order the `point` parameters were sent, separated by `;` (e.g. `sources=0;1`). `all` (default) uses every point.|
|destinations|int or string|no|all|Zero-based indices of the points to use as destinations, separated by `;` (e.g. `destinations=2;3;4;5`). `all` (default) uses every point.|
|annotation|string|no|duration|Enum: duration, distance|
## Example
### URL (Parameters)
```url
https://maps.vietmap.vn/api/matrix/v4?apikey={your-apikey}&point=10.768897,106.678505&point=10.765496,106.67626&point=10.7627936,106.6750729&point=10.7616745,106.6792425&point=10.765605,106.685383&point=10.766843,106.674029&sources=0;1&destinations=2;3;4;5
```
[:material-play-circle: Run this example on the Playground](https://tools.vietmap.vn/playground/matrix?point=10.768897,106.678505&point=10.765496,106.67626&point=10.7627936,106.6750729&point=10.7616745,106.6792425&point=10.765605,106.685383&point=10.766843,106.674029&sources=0;1&destinations=2;3;4;5){ .md-button .md-button--primary }
Query param description:
|Param|Value|Description|
|-----|-----|-------|
|point|10.768897,106.678505|`Point 0`, format in `lat,lng`|
|point|10.765496,106.67626|`Point 1`, format in `lat,lng`|
|point|10.7627936,106.6750729|`Point 2`, format in `lat,lng`|
|point|10.7616745,106.6792425|`Point 3`, format in `lat,lng`|
|point|10.765605,106.685383|`Point 4`, format in `lat,lng`|
|point|10.766843,106.674029|`Point 5`, format in `lat,lng`|
|sources|0;1|Index of the start point. In this example, API will receive `Point 0` and `Point 1` as source points|
|destinations|2;3;4;5|Index of the end point. In this example, API will receive `Point 2`, `Point 3`, `Point 4` and `Point 5` as the destination points|
### Response
```json
{
"code": "OK",
"messages": null,
"durations": [
[
230,
201,
386,
193
],
[
126,
188,
435,
108
]
],
"distances": [
[
1766.3,
1374.3,
1952.2,
1113.5
],
[
507.5,
1152.4,
2101.8,
399.4
]
]
}
```
### Response description
| Field | Type |Value| Description |
|------------|--------|-----|-----------------------------------------------|
| code | string | `'OK'` | A code indicating the status of the response. Details at [Status Code Values](#status-code-values) |
| messages | string | `null` | Messages associated with the response, if any. |
| durations | array | `[[230, 201, 386, 193 ], [ 126, 188, 435, 108 ]],` | `durations[i][j]` is the travel time in seconds from `sources[i]` to `destinations[j]` — one row per origin, one column per destination.  |
| distances | array | ` [[1766.3, 1374.3, 1952.2, 1113.5], [507.5, 1152.4, 2101.8, 399.4]]` | Same layout as `durations`, in meters.  |
### Status Code Values
- `OK`: The request was successful and the response contains valid data.
- `INVALID_REQUEST`: The request parameters failed validation. Details about the validation errors are provided in the messages field of the response.
- `OVER_DAILY_LIMIT`: The daily request limit for your API key has been exceeded. No further requests will be processed until the limit resets.
- `MAX_POINTS_EXCEED`: The number of points in the request URL exceeds the allowed maximum for your plan. Reduce the number of points and try again.
- `ERROR_UNKNOWN`: An unexpected error occurred while processing the API request. Please check the messages field for more information or contact support if the issue persists.
!!! tip "Try it with your own data"
Enter your own addresses, coordinates or parameters and see the result on a map, with a cURL command to copy: **[Open Matrix v4 on the Playground](https://tools.vietmap.vn/playground/matrix)**