Skip to content

Traveling Salesman Problem (TSP) v4

TSP

TSP v4 takes a list of points and returns the route for one vehicle through all of them with the lowest total driving time, with geometry and turn-by-turn instructions. Times come from the VIETMAP road network for the given vehicle (one-way streets and restrictions included). By default the route returns to the first point; change that with roundtrip, sources and destinations. For more than one vehicle use VRP.

Try it in the Playground

Call TSP 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.

TSP or VRP?

Your situation API
One vehicle, many stops — just tell me the order TSP v4 (this page)
Several vehicles — decide who takes what, then order each route VRP
I want raw travel times and will plan myself Distance Matrix
I know the order already, I need the road path Routing

Common setups

Situation Parameters
Start and end at the depot roundtrip=true (default)
Start at the depot, end anywhere roundtrip=false&sources=first
End at the last point you sent roundtrip=false&destinations=last
Need opening hours or load limits use VRP (time_windows, capacity)

Costing

A TSP request is billed as one transaction per stop — a 20-stop tour costs 20 transactions. See How Pricing Works.

URL

https://maps.vietmap.vn/api/tsp/v4?apikey={your-apikey}&point={point}&point={point}&point={point}&points_encoded={points_encoded}&vehicle={vehicle}&roundtrip={roundtrip}&destinations={destinations}&sources={sources}

Method

GET

Migrate from v3 → v4

  • The endpoint changes from /api/tsp/v3 to /api/tsp/v4.
  • TSP 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: TSP v3.

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 route should be calculated.
roundtrip boolean no true true (default): the route returns to the start point. false: open route; where it starts and ends is controlled by sources/destinations.
sources string no any any (default): the solver picks the start point. first: the route must start at the first point sent.
destinations string no any any (default): the solver picks the end point. last: the route must end at the last point sent (use with roundtrip=false).

Example

Input 

https://maps.vietmap.vn/api/tsp/v4?apikey={your-apikey}&point=10.79628438955497,106.70592293472612&point=10.801891047584164,106.70660958023404&point=10.801595962927763,106.6898296806408&points_encoded=true&vehicle=motorcycle&roundtrip=true
Response 
{
    "license": "vietmap",
    "code": "OK",
    "messages": null,
    "paths": [
        {
            "distance": 7720.5,
            "weight": 1022.8,
            "time": 1022800,
            "transfers": 0,
            "points_encoded": true,
            "bbox": [
                106.68973,
                10.79352,
                106.71098,
                10.80307
            ],
            "points": "}s{`Ac_hjSIP[r@KTuAxCOb@QVuAoAi@g@w@u@oCmC_BgBm@}@QUcB{C}@qBMYs@{B]}A_@kBSkCIo@oABFbAHtAPtAPpAbApDXv@Rj@dAzBT^dAdBqA^e@Jo@F{BLCcAAEICq@@p@AHB@DBbAzBMn@Gd@KpA_@LRZh@dAvAv@z@pI`I[t@u@vA|@h@LJDLa@jL?`AF^gBVeF~@GZuAb@sARgDr@uHfBa@PGBd@xAF\\?RGz@WnEk@~HSzCUlDH?bB?TnAJbAH|@?VBz@?j@?JGJGXGf@?n@Db@H~BjCn@?B?JAFI?}BCAcAI_CEc@?o@Fg@FYFK?K?k@C{@?WI}@KcAUoAdAAz@CP?`A?b@?z@CbAI\\E^GHAJ?VClAGbBGPA`ACLAv@CH?~BOj@C~@Al@Ar@C@kADKbDJ~@Bh@LGk@Bo@H[T[TOPGNCNA`AFlA@REVSFIFQBYGkA@{@Ig@[_AA}B@y@Hq@BO@g@EmAAWCg@Ac@BwAX_DHs@H{@DUP_@No@Be@?KEMGd@GJIDE?k@i@Q?WJGG}AqA?a@mAoAeDcDQQUUyEmEPWNc@tAyCJUZs@HQ",
            "instructions": [
                {
                    "distance": 192,
                    "heading": 0,
                    "sign": 0,
                    "interval": [
                        0,
                        6
                    ],
                    "text": "Tiếp tục theo Đường Nguyễn Cửu Vân",
                    "time": 25900,
                    "street_name": "Đường Nguyễn Cửu Vân",
                    "last_heading": null
                },
                {
                    "distance": 0,
                    "heading": 0,
                    "sign": 4,
                    "interval": [
                        201,
                        201
                    ],
                    "text": "Đích đến",
                    "time": 0,
                    "street_name": "Đường Nguyễn Cửu Vân",
                    "last_heading": null
                }
            ],
            "snapped_waypoints": "}s{`Ac_hjS}`@{CVphB"
        }
    ]
}

Response truncated; middle elements omitted.

Response description

Field Type Description
license string The type of license for the map data.
code string A code indicating the status of the response. Details at Status Code Values
messages null Messages associated with the response, if any.
paths array An array containing route information, such as distance, time, and instructions.

Each object in the paths array contains the following fields:

Field Type Description
distance float The total distance of the route (in meters).
weight float The weight of the route.
time integer The total time required to travel the route (in milliseconds).
transfers integer The number of transfers during the route.
points_encoded boolean Indicates whether the points are encoded.
bbox array The bounding box of the route.
points string Encoded points along the route.
instructions array An array containing step-by-step instructions for navigating the route.
snapped_waypoints string Snapped waypoints along the route.

Each object in the instructions array contains the following fields:

Field Type Description
distance float The distance of the instruction.
heading integer The heading direction of the instruction.
sign integer The sign indicating the action to take (e.g., turn left).
interval array The first and last index (of the points list) of the route section covered by this instruction.
text string The textual instruction for navigating.
time integer The time required to complete the instruction.
street_name string The name of the street for the instruction.
last_heading null The last heading direction for the instruction.

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.
  • ZERO_RESULTS: No viable route was found between the requested waypoints.

Frequently asked questions

When do I get ZERO_RESULTS?

When no road path connects all the point values sent for the selected vehicle. Check the coordinate order first (latitude, then longitude); if you are using vehicle=truck or container, call again with vehicle=car to see whether a point sits on a road closed to trucks.

facebook
Tổng đài hỗ trợ
089.616.4567 facebook Chat Facebook zalo Chat Zalo