Matrix Route API
GTEL MAPS Matrix Route API cho phép tính toán khoảng cách và thời gian di chuyển giữa nhiều địa điểm với nhiều phương thức di chuyển khác nhau (ô tô, xe máy, xe đạp, đi bộ, xe buýt, xe tải, taxi). Kết quả trả về là một ma trận với các thông tin chi tiết về khoảng cách và thời gian di chuyển giữa các địa điểm.
Dịch vụ này phù hợp cho các bài toán như tìm điểm gần nhất, tối ưu hóa lộ trình, phân bổ nguồn lực và các ứng dụng logistics thời gian thực.
Mục đích sử dụng
- Giúp đánh giá và so sánh khoảng cách hoặc thời gian di chuyển giữa nhiều cặp địa điểm một cách nhanh chóng và chính xác.
- Là nền tảng quan trọng để xây dựng các hệ thống giao hàng tối ưu, quản lý tuyến xe, hoặc định vị điểm gần nhất.
- Hỗ trợ phân tích không gian trong các ứng dụng như bất động sản, phân phối, giao thông, và dịch vụ theo vị trí (LBS).
- Dễ dàng tích hợp với các thuật toán tối ưu hóa như Travelling Salesman Problem (TSP) hay Vehicle Routing Problem (VRP).
| STT | Use Case | Mô tả tình huống | Cách giải quyết bằng Matrix API | Ví dụ cụ thể | Ứng dụng thực tế |
|---|---|---|---|---|---|
| 1 | Điều xe chữa cháy đến hiện trường nhanh nhất. | Một khu nhà đang cháy, cần tìm trạm cứu hỏa gần nhất để điều xe khống chế đám cháy. | 1. Lập danh sách tọa độ các trạm cứu hỏa (sources).2. Xác định tọa độ vị trí cháy ( targets).3. Gọi Matrix API để tính thời gian/khoảng cách từ từng trạm đến điểm cháy. 4. Chọn trạm có thời gian/khoảng cách nhỏ nhất. | Cháy tại Vincom Thủ Đức, hệ thống tính khoảng cách từ các trạm và chọn trạm gần nhất. | RapidDeploy RadiusPlus – Hệ thống hỗ trợ trung tâm 114 định vị xe cứu hỏa gần nhất và lập tuyến đường tối ưu.. |
| 2 | Tìm điểm trung gian cho họp lớp. | Nhiều thành viên từ các vị trí khác nhau, cần chọn điểm hẹn sao cho tổng thời gian di chuyển là thấp nhất. | 1. Lập danh sách tọa độ các thành viên (sources).2. Chọn các địa điểm hẹn tiềm năng ( target).3. Gọi Matrix API để tạo ma trận thời gian. 4. Tính tổng thời gian từ các sources đến từng targets.5. Chọn nơi có tổng thời gian nhỏ nhất. | Các thành viên ở nhiều nơi trong TP.HCM, hệ thống chọn quán cà phê trung tâm có tổng thời gian di chuyển ít nhất. | MeetWays – Nền tảng giúp tìm điểm hẹn giữa hai hoặc nhiều người từ các vị trí khác nhau để tối ưu khoảng cách. |
| 3 | Tối ưu thứ tự ghé qua nhiều điểm (TSP). | Người dùng có nhiều điểm cần đi qua (giao hàng, du lịch…) và muốn có lộ trình ngắn nhất. | 1. Lập danh sách tất cả các điểm cần ghé (bao gồm cả điểm xuất phát). 2. Gọi Matrix API để tính ma trận thời gian/khoảng cách giữa các điểm (tất cả điểm là sources và target).3. Áp dụng thuật toán TSP để tìm thứ tự đi qua các điểm tối ưu. | Shipper có 8 điểm giao hàng ở Hà Nội, hệ thống tính ma trận 8×8 và tối ưu thứ tự giao để giảm quãng đường | Route4Me – Nền tảng tối ưu hóa tuyến đường cho giao hàng, sử dụng ma trận khoảng cách và thuật toán TSP. |
| 4 | Cảnh báo phạt chậm trễ (ETA). | Theo dõi lộ trình xe để phát hiện khả năng trễ và cảnh báo khi vượt quá thời gian cam kết. | 1. Định kỳ lấy tọa độ vị trí hiện tại của xe (sources) và điểm đích (targets).2. Gọi Matrix API để tính thời gian còn lại. 3. Cộng thời gian đã đi với thời gian còn lại. 4. So sánh với thời hạn SLA. 5. Nếu vượt quá, kích hoạt cảnh báo. | Xe giao hàng đã đi 20 phút, còn 15 phút mới tới — hệ thống cảnh báo vì vượt (SLA) 30 phút. | Amazon Logistics ETA Prediction System – Theo dõi tiến trình giao hàng và cảnh báo khi đơn hàng có nguy cơ trễ. |
| 5 | Phân bổ taxi theo tổng thời gian tối ưu. | Có nhiều xe taxi và nhiều khách hàng cần đón, cần phân phối sao cho tổng thời gian chờ và di chuyển là thấp nhất. | 1. Lập danh sách tọa độ các xe taxi (sources).2. Lập danh sách tọa độ các khách hàng ( target).3. Gọi Matrix API để tạo ma trận thời gian. 4. Áp dụng thuật toán phân công. 5. Chọn các cặp taxi–khách với tổng thời gian nhỏ nhất. | Trong giờ cao điểm, từ 20 taxi và 100 khách gọi xe, hệ thống chọn ra 20 cặp tài xế–khách tối ưu nhất. | Uber Dispatch System – Tự động ghép tài xế và khách hàng gần nhất bằng hệ thống tính toán khoảng cách thời gian. |
Dịch vụ Matrix Route API
Loading...
| Tham số bắt buộc | Kiểu dữ liệu | Mô tả |
|---|---|---|
sources | string | Danh sách điểm xuất phát dùng để tính toán khoảng cách và thời gian di chuyển. Giới hạn tối đa cho sources và targets là source x target ≤ 100. Hỗ trợ định dạng: - lat,lon - lat,lon|lat,lon (phân cách bằng dấu |) |
targets | string | Danh sách điểm đích, tương tự như sources. Lưu ý: Kiểu dữ liệu của targets giống với sources. |
| Tham số tuỳ chọn | Kiểu dữ liệu | Mô tả |
|---|---|---|
mode | string | Phương thức di chuyển (mặc định: DRIVING): - DRIVING: Ô tô, xe máy, xe tải tiêu chuẩn tuân thủ luật giao thông - WALKING: Đi bộ, ưu tiên đường ngắn nhất và tránh cầu thang - BICYCLING: Xe đạp, ưu tiên đường dành cho xe đạp - BUS: Xe buýt, kế thừa từ DRIVING nhưng kiểm tra làn xe buýt - TRUCK: Xe tải, kiểm tra hạn chế trọng tải và kích thước - TAXI: Taxi, ưu tiên làn taxi - MOTO_SCOOTER: Xe máy/xe ga, tránh đường cao tốc |
id | string | Định danh yêu cầu, tên định danh tùy ý để trace/log yêu cầu matrix. |
matrix_locations | integer | Tham số này cho phép bạn chỉ định số lượng tối thiểu các điểm cần được tính toán kết quả trong ma trận. Hữu ích trong các trường hợp: - Một số điểm không thể định tuyến được do lỗi bản đồ hoặc giới hạn dữ liệu. - Bạn chỉ quan tâm đến n điểm gần nhất hoặc khả thi nhất thay vì toàn bộ tập điểm. Nếu matrix_locations được chỉ định, service có thể trả về kết quả một phần (partial) thay vì toàn bộ kết quả. Ví dụ: ?matrix_locations=3 → Trả về tối đa 3 tuyến đường tốt nhất. |
shape_format | string | Định dạng hình dạng đường đi cho mỗi kết nối trong ma trận (mặc định: no_shape): - polyline6: Trả về đường đi được mã hóa polyline với độ chính xác 6 - polyline5: Trả về đường đi được mã hóa polyline với độ chính xác 5 - geojson: Trả về đường đi dưới dạng GeoJSON LineString geometry - no_shape: Không bao gồm hình dạng đường đi trong phản hồi (mặc định) Ví dụ: shape_format=polyline6 → Yêu cầu bao gồm hình dạng đường đi được mã hóa định dạng polyline6. |
costing_options | object | Cấu hình chi tiết cho từng phương thức di chuyển. Định dạng: costing_options.{mode}.{option}={value} Ví dụ: costing_options.driving.shortest=true&costing_options.driving.use_highways=0.2 Cho phép tùy chỉnh các yếu tố như tốc độ, tránh cao tốc, ưu tiên đường ngắn, v.v. Xem chi tiết: Bảng Costing Options bên dưới. |
Yêu cầu mẫu: Dịch vụ Matrix Route API
Loading...
Cấu trúc phản hồi mẫu: Dịch vụ Matrix Route API
| Thuộc tính | Kiểu dữ liệu | Mô tả |
|---|---|---|
id | string | Mã định danh của request, chỉ có nếu được khai báo trong input. |
units | string | Đơn vị đo khoảng cách (kilometers hoặc miles). Mặc định là kilometers. |
sources | array | Danh sách điểm xuất phát giống như trong request. |
targets | array | Danh sách điểm đích giống như trong request. |
sources_to_targets | array | Mảng 2 chiều chứa thông tin từ từng source đến từng target. Mỗi phần tử là object chứa chi tiết về khoảng cách, thời gian và các thông số khác. |
distance | number | Khoảng cách giữa các điểm (sẽ bằng 0.0 nếu là cùng điểm). |
time | integer | Thời gian di chuyển (sẽ bằng 0 nếu là cùng điểm). |
from_index | integer | Chỉ số của source trong mảng input. |
to_index | integer | Chỉ số của target trong mảng input. |
begin_heading | integer | Góc hướng đầu tuyến đường (độ). |
end_heading | integer | Góc hướng cuối tuyến đường (độ). |
begin_lat | number | Vĩ độ của source tương ứng. |
begin_lon | number | Kinh độ của source tương ứng. |
end_lat | number | Vĩ độ của target tương ứng. |
end_lon | number | Kinh độ của target tương ứng. |
Phản hồi mẫu: Dịch vụ Matrix Route API
{
"status": "OK",
"data": {
"algorithm": "costmatrix",
"units": "kilometers",
"sources": [
{
"lon": 106.690804,
"lat": 10.766312
},
{
"lon": 106.695832,
"lat": 10.765747
}
],
"targets": [
{
"lon": 106.694749,
"lat": 10.762979
},
{
"lon": 106.694725,
"lat": 10.761395
}
],
"sources_to_targets": [
[
{
"begin_lon": 106.690804,
"begin_lat": 10.766312,
"end_heading": 229,
"begin_heading": 303,
"end_lon": 106.690804,
"distance": 1.63,
"end_lat": 10.766312,
"time": 171,
"to_index": 0,
"from_index": 0
},
{
"begin_lon": 106.690804,
"begin_lat": 10.766312,
"end_heading": 334,
"begin_heading": 303,
"end_lon": 106.690804,
"distance": 1.98,
"end_lat": 10.766312,
"time": 188,
"to_index": 1,
"from_index": 0
}
],
[
{
"begin_lon": 106.695832,
"begin_lat": 10.765747,
"end_heading": 49,
"begin_heading": 230,
"end_lon": 106.695832,
"distance": 0.647,
"end_lat": 10.765747,
"time": 82,
"to_index": 0,
"from_index": 1
},
{
"begin_lon": 106.695832,
"begin_lat": 10.765747,
"end_heading": 334,
"begin_heading": 50,
"end_lon": 106.695832,
"distance": 0.927,
"end_lat": 10.765747,
"time": 87,
"to_index": 1,
"from_index": 1
}
]
]
},
"licence": "© GTEL Maps"
}
Costing Options
Tham số costing_options cho phép bạn tùy chỉnh chi tiết cách tính toán tuyến đường cho từng phương thức di chuyển. Sử dụng định dạng: costing_options.{mode}.{option}={value}
Tùy chọn tính chi phí cho phương tiện di chuyển trên đường (áp dụng cho driving, bus, truck)
| Tùy chọn | Mô tả | Giá trị mặc định |
|---|---|---|
maneuver_penalty | Phạt khi chuyển đổi giữa các đường có tên không nhất quán (0.0-43200.0 giây) | 5 |
gate_cost | Chi phí khi gặp cổng có quyền truy cập không xác định/riêng tư (0.0-43200.0 giây) | 30 |
gate_penalty | Phạt cho cổng không có thông tin truy cập (0.0-43200.0 giây) | 300 |
private_access_penalty | Phạt cho cổng/rào chắn có quyền truy cập riêng tư (0.0-43200.0 giây) | 450 |
destination_only_penalty | Phạt cho đường chỉ được phép đi để đến đích (0.0-43200.0 giây) | - |
toll_booth_cost | Chi phí khi gặp trạm thu phí (0.0-43200.0 giây) | 15 |
toll_booth_penalty | Phạt cho trạm thu phí để tránh đường có phí (0.0-43200.0 giây) | 0 |
ferry_cost | Chi phí khi sử dụng phà (0.0-43200.0 giây) | 300 |
use_ferry | Mức độ sẵn sàng sử dụng phà (0.0-1.0) | 0.5 |
use_highways | Mức độ sẵn sàng sử dụng cao tốc (0.0-1.0) | 0.5 |
use_tolls | Mức độ sẵn sàng sử dụng đường có phí (0.0-1.0) | 0.5 |
use_living_streets | Mức độ sẵn sàng sử dụng đường dân cư (0.0-1.0) | 0 (xe tải), 0.1 (khác) |
use_tracks | Mức độ sẵn sàng sử dụng đường mòn (0.0-1.0) | 0 (ô tô), 0.5 (xe máy) |
service_penalty | Phạt cho đường dịch vụ chung (0.0-43200.0 giây) | 0 (xe tải), 15 (khác) |
service_factor | Hệ số chi phí cho đường dịch vụ (0.1-100000.0) | 1 |
country_crossing_cost | Chi phí khi qua biên giới quốc tế (0.0-43200.0 giây) | 600 |
country_crossing_penalty | Phạt khi qua biên giới (0.0-43200.0 giây) | 0 |
shortest | Chỉ sử dụng tính toán dựa trên khoảng cách (true/false) | false |
use_distance | Cân bằng giữa khoảng cách và thời gian (0.0-1.0, chỉ ô tô) | 0 |
disable_hierarchy_pruning | Tính toán tuyến đường tối ưu thực sự (true/false) | false |
top_speed | Tốc độ tối đa của xe (km/h, 10-252) | 140 (ô tô/xe buýt), 120 (xe tải) |
fixed_speed | Ghi đè tốc độ tính toán (km/h, 1-252, 0=tắt) | 0 |
ignore_closures | Bỏ qua đóng đường theo thời gian thực (true/false) | false |
closure_factor | Hệ số phạt cho đường bị đóng (1.0-10.0) | 9.0 |
ignore_restrictions | Bỏ qua hạn chế rẽ/kích thước (true/false) | false |
ignore_oneways | Bỏ qua hạn chế một chiều (true/false) | false |
ignore_non_vehicular_restrictions | Bỏ qua hạn chế không liên quan an toàn (true/false) | false |
ignore_access | Bỏ qua thẻ truy cập theo phương thức (true/false) | false |
ignore_construction | Bỏ qua thẻ xây dựng (true/false) | false |
Tùy chọn kích thước xe (áp dụng cho driving, bus, taxi, truck)
| Tùy chọn | Mô tả | Giá trị mặc định |
|---|---|---|
height | Chiều cao xe (mét) | 1.9 (ô tô/xe buýt/taxi), 4.11 (xe tải) |
width | Chiều rộng xe (mét) | 1.6 (ô tô/xe buýt/taxi), 2.6 (xe tải) |
exclude_unpaved | Tránh đường không trải nhựa ở giữa tuyến (true/false) | false |
exclude_cash_only_tolls | Tránh đường thu phí chỉ nhận tiền mặt (true/false) | false |
include_hov2 | Bao gồm đường HOV-2 khi có lợi (true/false) | false |
include_hov3 | Bao gồm đường HOV-3 khi có lợi (true/false) | false |
include_hot | Bao gồm đường HOV có phí (true/false) | false |
Tùy chọn cho xe tải (truck)
| Tùy chọn | Mô tả | Giá trị mặc định |
|---|---|---|
length | Chiều dài xe tải (mét) | 21.64 |
weight | Trọng lượng xe tải (tấn) | 21.77 |
axle_load | Tải trọng trục xe (tấn) | 9.07 |
axle_count | Số trục xe | 5 |
hazmat | Xe chở hàng nguy hiểm (true/false) | false |
hgv_no_access_penalty | Phạt cho đường không cho phép xe tải (0.0-43200.0 giây) | 43200 |
low_class_penalty | Phạt cho đường dân cư hoặc dịch vụ (0.0-43200.0 giây) | 30 |
use_truck_route | Ưu tiên tuyến đường dành cho xe tải (0.0-1.0) | 0 |
Tùy chọn cho xe đạp (bicycling)
| Tùy chọn | Mô tả | Giá trị mặc định |
|---|---|---|
bicycle_type | Loại xe đạp: road, hybrid, city, cross, mountain | hybrid |
cycling_speed | Tốc độ trung bình trên đường bằng phẳng (km/h) | 25 (road), 20 (cross), 18 (hybrid/city), 16 (mountain) |
use_roads | Mức độ sẵn sàng đi chung đường với xe cộ (0.0-1.0) | 0.5 |
use_hills | Mức độ sẵn sàng leo đồi (0.0-1.0) | 0.5 |
use_ferry | Mức độ sẵn sàng sử dụng phà (0.0-1.0) | 0.5 |
use_living_streets | Mức độ sẵn sàng sử dụng đường dân cư (0.0-1.0) | 0.5 |
avoid_bad_surfaces | Tránh đường có mặt đường xấu (0.0-1.0) | 0.25 |
bss_return_cost | Thời gian trả xe đạp thuê (giây, chế độ bikeshare) | 120 |
shortest | Chỉ sử dụng tính toán dựa trên khoảng cách (true/false) | false |
maneuver_penalty | Phạt khi chuyển đổi giữa các đường có tên không nhất quán (0.0-43200.0 giây) | 5 |
gate_cost | Chi phí khi gặp cổng có quyền truy cập không xác định/riêng tư (0.0-43200.0 giây) | 30 |
gate_penalty | Phạt cho cổng không có thông tin truy cập (0.0-43200.0 giây) | 300 |
destination_only_penalty | Phạt cho đường chỉ được phép đi để đến đích (0.0-43200.0 giây) | - |
country_crossing_cost | Chi phí khi qua biên giới quốc tế (0.0-43200.0 giây) | 600 |
country_crossing_penalty | Phạt khi qua biên giới (0.0-43200.0 giây) | 0 |
service_penalty | Phạt cho đường dịch vụ chung (0.0-43200.0 giây) | 15 |
Tùy chọn cho xe máy/xe tay ga (moto_scooter)
| Tùy chọn | Mô tả | Giá trị mặc định |
|---|---|---|
top_speed | Tốc độ tối đa xe máy (km/h, 20-120, để tránh đường nhanh) | 45 |
use_primary | Mức độ sẵn sàng sử dụng đường chính (0.0-1.0, 0=tránh đường chính, 1=thoải mái trên đường chính) | 0.5 |
use_hills | Mức độ sẵn sàng leo đồi (0.0-1.0, 0=tránh đồi, 1=không sợ đồi) | 0.5 |
shortest | Chỉ sử dụng tính toán dựa trên khoảng cách (true/false) | false |
disable_hierarchy_pruning | Tính toán tuyến đường tối ưu thực sự (true/false, ảnh hưởng hiệu suất) | false |
Tùy chọn cho đi bộ (walking)
| Tùy chọn | Mô tả | Giá trị mặc định |
|---|---|---|
walking_speed | Tốc độ đi bộ (km/h, 0.5-25) | 5.1 |
walkway_factor | Hệ số ưu tiên đường dành cho người đi bộ | 1.0 |
sidewalk_factor | Hệ số ưu tiên đường có vỉa hè | 1.0 |
alley_factor | Hệ số tránh đường hẻm (để tránh đường hẹp) | 2.0 |
driveway_factor | Hệ số tránh đường lái xe riêng (để tránh đường tư) | 5.0 |
step_penalty | Phạt cho đường có bậc thang hoặc cầu thang (giây) | - |
elevator_penalty | Phạt cho việc chuyển đổi thang máy (giây) | - |
use_ferry | Mức độ sẵn sàng sử dụng phà (0.0-1.0) | 0.5 |
use_living_streets | Mức độ sẵn sàng sử dụng đường dân cư (0.0-1.0) | 0.6 |
use_tracks | Mức độ sẵn sàng sử dụng đường mòn (0.0-1.0) | 0.5 |
use_hills | Mức độ chấp nhận leo đồi và độ dốc (0.0-1.0) | 0.5 |
use_lit | Ưu tiên đường có đèn (0.0-1.0, 1=tránh đường không có đèn) | 0 |
service_penalty | Phạt cho đường dịch vụ chung (giây) | 0 |
service_factor | Hệ số chi phí cho đường dịch vụ chung | 1.0 |
destination_only_penalty | Phạt cho đường chỉ được phép đi để đến đích (0.0-43200.0 seconds) | - |
max_hiking_difficulty | Độ khó tối đa của đường mòn leo núi (0-6, dựa trên sac_scale) | 1 |
bss_rent_cost | Thời gian thuê xe đạp từ trạm bikeshare (giây) | 120 |
bss_rent_penalty | Phạt khi thuê xe đạp bikeshare (sử dụng thuật toán nội bộ) | - |
shortest | Chỉ sử dụng tính toán dựa trên khoảng cách (true/false) | false |
max_distance | Khoảng cách đi bộ tối đa của tuyến đường (km) | 100 |
transit_start_end_max_distance | Khoảng cách đi bộ tối đa ở đầu/cuối tuyến (mét) | 2145 |
transit_transfer_max_distance | Khoảng cách đi bộ tối đa giữa các chuyển đổi (mét) | 800 |
type | Loại định tuyến đặc biệt: blind (hướng dẫn bổ sung), wheelchair (mặc định điều chỉnh), foot (tiêu chuẩn) | foot |
mode_factor | Hệ số nhân chi phí cạnh người đi bộ trong yêu cầu đa phương thức | 1.5 |
Ví dụ sử dụng Costing Options
# Ô tô ưu tiên đường ngắn và tránh cao tốc
?mode=DRIVING&costing_options.driving.shortest=true&costing_options.driving.use_highways=0.1
# Xe tải với kích thước cụ thể
?mode=TRUCK&costing_options.truck.height=3.5&costing_options.truck.weight=15&costing_options.truck.length=12
# Xe đạp đường trường với tốc độ cao
?mode=BICYCLING&costing_options.bicycling.bicycle_type=road&costing_options.bicycling.cycling_speed=30
# Đi bộ với tốc độ chậm và tránh đồi
?mode=WALKING&costing_options.walking.walking_speed=3&costing_options.walking.use_hills=0.1