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; to split stops across vehicles use VRP.

Playground¶

Try it in the Playground

Call Matrix v4 with real data, no code required: Open Playground

AI Agent Integration NEW

Download the optimized doc for AI agent integration (Matrix + TSP + VRP): Logistics Agent Doc

Or try it in Postman.

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, 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
apikey	string	yes	none	API key provided by VIETMAP for your account. Register here
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)¶

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

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¶

{
    "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 ]],`	`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.