Skip to content

Matrix v4


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 · Machine-readable schema: OpenAPI 3.1

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
curl -G 'https://maps.vietmap.vn/api/matrix/v4' \
  --data-urlencode 'apikey=YOUR_API_KEY' \
  --data-urlencode 'point=10.768897,106.678505' \
  --data-urlencode 'point=10.765496,106.67626' \
  --data-urlencode 'point=10.7627936,106.6750729' \
  --data-urlencode 'point=10.7616745,106.6792425' \
  --data-urlencode 'point=10.765605,106.685383' \
  --data-urlencode 'point=10.766843,106.674029' \
  --data-urlencode 'sources=0;1' \
  --data-urlencode 'destinations=2;3;4;5'
// Node.js 18+. Call from your server so the API key stays private.
const params = new URLSearchParams([
  ["apikey", "YOUR_API_KEY"],
  ["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"],
]);
const res = await fetch(`https://maps.vietmap.vn/api/matrix/v4?${params}`);
const data = await res.json();
console.log(data);
import requests

params = [
    ("apikey", "YOUR_API_KEY"),
    ("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"),
]
resp = requests.get("https://maps.vietmap.vn/api/matrix/v4", params=params, timeout=10)
resp.raise_for_status()
print(resp.json())
Integrate the VIETMAP Matrix v4 API into my project.

Sample request (from the example in the docs):
GET https://maps.vietmap.vn/api/matrix/v4
  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

Requirements:
- Call the API from the server. Read the API key from the VIETMAP_API_KEY environment variable and send it as `apikey`; never hard-code it.
- Write one function that sends this request, checks the HTTP status and returns the parsed response.
- Read the docs below first. Use only parameters and response fields documented there.

Docs:
- https://maps.vietmap.vn/docs/map-api/matrix-version/matrix-v4/index.txt
- https://maps.vietmap.vn/docs/assets/agents/logistics.txt

Run this example on the Playground

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. Row/column layout of the durations matrix
distances array [[1766.3, 1374.3, 1952.2, 1113.5], [507.5, 1152.4, 2101.8, 399.4]] Same layout as durations, in meters. Row/column layout of the distances matrix

Status Code Values

How to handle each code, and the HTTP statuses: Error codes.

  • 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.

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

  • Route v4 — the full path between two or more points.
  • TSP v4 — let the API pick the visiting order for one vehicle.
  • VRP — split stops across several vehicles.
  • Isochrone — the area reachable within a travel time.
Hotline
Tổng đài hỗ trợ
089.616.4567
Messenger Chat Facebook zalo Chat Zalo