Bỏ qua

Traveling Salesman Problem (TSP) v4

TSP

TSP v4 nhận danh sách điểm và trả về tuyến cho một xe đi qua tất cả điểm với tổng thời gian chạy nhỏ nhất, kèm geometry và hướng dẫn rẽ. Thời gian tính trên mạng đường VIETMAP theo vehicle (có tính đường một chiều, đường cấm). Mặc định quay về điểm đầu; đổi bằng roundtrip, sources, destinations. Nhiều xe thì dùng VRP.

Thử ngay trên Playground

Gọi thử TSP v4 với dữ liệu thật, không cần viết code: Mở Playground

Tích hợp AI Agent ✨ MỚI

Tải bộ tài liệu đã tối ưu cho AI agent (Matrix + TSP + VRP): Logistics Agent Doc

Hoặc dùng thử bằng Postman.

Chọn TSP hay VRP?

Tình huống của bạn API
Một xe, nhiều điểm — chỉ cần biết thứ tự TSP v4 (trang này)
Nhiều xe — chia ai đi điểm nào rồi mới sắp thứ tự từng tuyến VRP
Chỉ cần thời gian đi thô, tự lập kế hoạch Distance Matrix
Đã biết thứ tự, chỉ cần đường đi Routing

Cấu hình theo tình huống

Tình huống Tham số
Xuất phát từ kho, về lại kho roundtrip=true (mặc định)
Xuất phát từ kho, kết thúc ở điểm bất kỳ roundtrip=false&sources=first
Kết thúc đúng ở point cuối cùng gửi lên roundtrip=false&destinations=last
Cần ràng buộc giờ mở cửa hoặc tải trọng dùng VRP (time_windows, capacity)

Cách tính tiền

Một lượt gọi TSP tính một transaction cho mỗi điểm dừng — lộ trình 20 điểm tốn 20 transaction. Xem Cách tính tiền.

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

Chuyển từ v3 lên v4

  • Endpoint đổi từ /api/tsp/v3 sang /api/tsp/v4.
  • TSP v4 chạy trên cùng bộ máy định tuyến v4 với Route v4, nên kết quả khớp với tuyến v4.
  • Tham số request và định dạng phản hồi giữ nguyên, nên chuyển đổi chỉ là đổi URL.

Xem tài liệu bản cũ: TSP v3.

Tham số

Tham số Kiểu Bắt buộc Mặc định Mô tả
apikey string có không API key VIETMAP cấp cho tài khoản của bạn. Đăng ký tại đây
point array string có không Các điểm cần tính tuyến. Định dạng [latitude,longitude] — vĩ độ trước. Ít nhất phải có điểm đi và điểm đến; có thể thêm điểm trung gian. Số điểm tối đa tùy theo gói bạn đang dùng.
Ví dụ: &point=10.762622,106.660172
points_encoded boolean không true Chọn cách mã hóa tọa độ trả về trong points và snapped_waypoints. true: chuỗi polyline google polyline 5 — payload nhỏ, phía client phải dùng thư viện polyline để giải mã. false: trả về mảng tọa độ thô, đọc được ngay. Mặc định true.
Chúng tôi khuyên để true để giảm kích thước JSON phản hồi.
vehicle string không car Enum: car, motorcycle, truck, container. Chọn loại phương tiện để tính tuyến.
roundtrip boolean không true true (mặc định): tuyến quay về điểm xuất phát. false: tuyến hở, không quay về; điểm đầu/cuối do sources/destinations quyết định.
sources string không any any (mặc định): bộ giải tự chọn điểm bắt đầu. first: bắt buộc bắt đầu ở point đầu tiên gửi lên.
destinations string không any any (mặc định): bộ giải tự chọn điểm kết thúc. last: bắt buộc kết thúc ở point cuối cùng gửi lên (dùng cùng roundtrip=false).

Ví dụ

Đầu vào 

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
Phản hồi 
{
    "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 rút gọn, đã lược các phần tử ở giữa.

Mô tả phản hồi

Trường Kiểu Mô tả
license string Loại giấy phép của dữ liệu bản đồ.
code string Mã trạng thái của phản hồi. Chi tiết ở Các mã trạng thái
messages null Thông báo kèm theo phản hồi, nếu có.
paths array Mảng chứa thông tin tuyến đường: quãng đường, thời gian và hướng dẫn đi.

Mỗi phần tử trong mảng paths gồm các trường sau:

Trường Kiểu Mô tả
distance float Tổng quãng đường của tuyến (mét).
weight float Trọng số của tuyến.
time integer Tổng thời gian đi hết tuyến (mili giây).
transfers integer Số lần chuyển tuyến trong hành trình.
points_encoded boolean Cho biết các điểm có được mã hóa hay không.
bbox array Khung bao của tuyến.
points string Chuỗi điểm đã mã hóa dọc theo tuyến.
instructions array Mảng chứa hướng dẫn đi từng bước trên tuyến.
snapped_waypoints string Các điểm đã bám vào đường dọc theo tuyến.

Mỗi phần tử trong mảng instructions gồm các trường sau:

Trường Kiểu Mô tả
distance float Quãng đường của bước hướng dẫn này, tính bằng mét
heading integer Hướng đi tại bước này, tính bằng độ (0 = Bắc)
sign integer Mã chỉ hành động cần làm (ví dụ rẽ trái).
interval array Chỉ số đầu và cuối (trong mảng points) của đoạn tuyến mà hướng dẫn này nói tới.
text string Nội dung hướng dẫn dạng chữ.
time integer Thời gian đi hết bước này, tính bằng mili giây
street_name string Tên đường của bước hướng dẫn.
last_heading null Hướng đi cuối của bước hướng dẫn.

Các mã trạng thái

  • OK: Yêu cầu thành công, phản hồi chứa dữ liệu hợp lệ.
  • INVALID_REQUEST: Tham số gửi lên không hợp lệ. Chi tiết lỗi nằm trong trường messages của phản hồi.
  • OVER_DAILY_LIMIT: API key đã vượt hạn mức lượt gọi trong ngày. Các lượt gọi tiếp theo sẽ không được xử lý cho tới khi hạn mức được đặt lại.
  • MAX_POINTS_EXCEED: Số điểm trong URL vượt quá mức tối đa của gói bạn đang dùng. Bạn giảm bớt số điểm rồi gọi lại.
  • ERROR_UNKNOWN: Có lỗi ngoài dự kiến khi xử lý yêu cầu. Bạn xem trường messages để biết thêm, hoặc liên hệ hỗ trợ nếu vẫn không được.
  • ZERO_RESULTS: Không tìm được tuyến đường khả thi giữa các điểm yêu cầu.

Câu hỏi thường gặp

Khi nào gặp ZERO_RESULTS?

Khi không có đường đi nối tất cả point trên mạng đường của vehicle đã chọn. Kiểm tra thứ tự toạ độ trước (phải là vĩ độ trước, kinh độ sau); nếu đang dùng vehicle=truck hoặc container, gọi lại với vehicle=car để biết có phải điểm nằm trên đường cấm xe tải hay không.

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