Matrix¶
The Matrix API is part of the VIETMAP Directions API and with it you can calculate many-to-many distances and times a lot more efficient than calling the Routing API multiple times.
In the Routing API we support multiple points, so called 'via points', which results in one route being calculated. The Matrix API results in NxM routes, or more precise NxM distances or times being calculated but is a lot faster compared to NxM single requests.
The most simple example is a tourist trying to decide which pizza is close to her instead of using beeline distance she can calculate a 1x4 matrix. Or a delivery service often in the need of big NxN matrices to solve vehicle routing problems.
Some other use cases for the Matrix API:
- Logistic problems often pick up many items from and deliver them to many locations.
- Calculating detours with many possible points in-between and selecting the best e.g. interesting for ridesharing or taxi applications. For this 1-to-many requests are necessary.
- Finding the best tour for a tourist in the need to visit as many points of interests as possible.
Playground¶
You can test the Matrix API in our VietMap Matrix API Playground.
AI Agent Integration 
NEW
Download the optimized doc for AI agent integration (Matrix + TSP + VRP): Logistics Agent Doc
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.1to/api/matrix/v4(theapi-versionquery parameter is no longer used). - Matrix v4 runs on the same v4 routing engine as 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.
Parameters¶
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| 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 | Format : [{index};{index}[;{index} ...] or all. Use location with given index as source. This is list of starting points. For example, having a total of 7 points, the first 2 points are called the source, the remaining 5 points are called the destination. then the index of sources is [0;1]. If you enter 2 or more locations, separate them with a semicolon ";" |
| destinations | int or string | no | all | Format: [{index};{index}[;{index} ...] or all. Use location with given index as destination. This is list index of destinations. For example, having a total of 7 points, the first 2 points are called the source, the remaining 5 points are called the destination. then the index of destinations is [2;3;4;5]. If you enter 2 or more locations, separate them with a semicolon ";" |
| annotation | string | no | duration | Enum: duration, distance |
Example¶
URL (Parameters)¶
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
| 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¶
{
"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 |
| messages | string | null |
Messages associated with the response, if any. |
| durations | array | [[230, 201, 386, 193 ], [ 126, 188, 435, 108 ]], |
An array containing duration information (seconds).  |
| distances | array | [[1766.3, 1374.3, 1952.2, 1113.5], [507.5, 1152.4, 2101.8, 399.4]] |
An array containing distance information (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.
