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.

URL¶

https://maps.vietmap.vn/api/matrix?api-version=1.1&apikey={your-apikey}&point={point}&point={point}&point={point}&points_encoded={points_encoded}&vehicle={vehicle}&sources={sources}&destinations={destinations}&annotation={annotation}

Method¶

GET

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	int or string	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`, `bike`, `foot`, `motorcycle`. The vehicle profile for which the route 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?api-version=1.1&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.6792429	`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.
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).