Skip to content

Traveling Salesman Problem (TSP)

TSP

The Traveling Salesman Problem (TSP) is a well-known mathematical problem in computer science and operations research. Given a set of cities and the distances between them, the TSP requires finding the shortest possible route that visits each city exactly once and returns to the starting city. This problem can be applied to the context of maps and routing, where the cities represent locations and the distances represent travel distances or travel times.

A Traveling Salesman Problem (TSP) Maps API refers to a set of functions or tools provided by VIETMAP that help developers to solve the TSP for a given set of locations. These APIs may provide algorithms or heuristics for finding approximate solutions to the TSP, as well as visualization tools for displaying the resulting routes on a map. Developers can use TSP Maps APIs to create applications that help optimize route planning and navigation, such as delivery optimization, logistics management, and more.

AI Agent Integration ✨ NEW

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

The Traveling Salesman Problem (TSP) asks a simple question with a hard answer: given a set of stops, what order should one vehicle visit them in to keep the total trip as short as possible and still return to the start? The VIETMAP TSP API answers it on the real Vietnamese road network, so the order it returns reflects actual driving time — one-way streets, road classes and vehicle profile included — not straight-line distance.

The number of possible orders grows factorially: 10 stops already have over 3 million possible sequences, which is why route order is worth solving rather than guessing.

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

What you can build with it

Use case What TSP gives you
One rider's delivery round The stop order that gets today's parcels delivered in the least time on the road.
Field service visits A technician's day sorted so travel between appointments is minimal.
Collection routes Pickups ordered to return to the depot before it closes.
Sales / merchandiser visits A visit sequence across outlets that fits inside working hours.
Tourism itineraries An order of attractions that minimises time spent moving between them.

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 (short)

  • 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 Values : true (default), false. Returned route is a roundtrip (route returns to first location)
sources string no any Values: any (default), first. Returned route start at any or first coordinate
destinations string no any Values: any (default), last. Returned route ends at any or last coordinate

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
                },
                /// More instruction objects will response here
                {
                    "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 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

What is a TSP API?

A TSP (Traveling Salesman Problem) API takes a list of stops and returns the order one vehicle should visit them in to minimise total travel, returning to the start. VIETMAP computes it on the real road network, so the answer reflects driving time rather than straight-line distance.

When should I use TSP instead of VRP?

Use TSP when a single vehicle serves all the stops and you only need the order. Use VRP as soon as more than one vehicle is involved, because then the hard part is deciding who takes what before ordering anything.

Does TSP account for one-way streets and vehicle type?

Yes. The tour is computed on the VIETMAP road network with a vehicle profile, so one-way streets, road classes and vehicle restrictions shape the resulting order.

How many transactions does one TSP call cost?

One transaction per stop — a 20-stop tour costs 20 transactions. See How Pricing Works.

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