DISTANCE MATRIX (V2)

TỔNG QUAN

Distance Matrix API v2 là công cụ hỗ trợ tính toán khoảng cách và thời gian di chuyển giữa nhiều cặp điểm cùng lúc. Được ứng dụng phổ biến trong các bài toán tối ưu vận hành như: lập kế hoạch giao hàng, điều phối xe theo lộ trình tối ưu, gọi xe theo thời gian thực, hay quản lý năng lực vận chuyển trong hệ thống logistics phức tạp.

Phiên bản v2 được nâng cấp với nhiều cải tiến quan trọng. Đáng chú ý nhất là tùy chọn administrative_unit, cho phép người dùng linh hoạt lựa chọn cách xử lý dữ liệu theo địa giới hành chính — có thể lấy theo ranh giới hành chính mới sau sáp nhập, hoặc giữ nguyên theo cấu trúc địa giới cũ. Tính năng này đặc biệt phù hợp trong bối cảnh Việt Nam đang tái tổ chức đơn vị hành chính cấp huyện, xã tại nhiều tỉnh thành.

API vẫn duy trì cấu trúc phản hồi JSON quen thuộc, đảm bảo khả năng tích hợp nhanh chóng với các hệ thống hiện có trong lĩnh vực logistics, điều hành giao thông, du lịch, quản lý hạ tầng đô thị và nhiều ứng dụng phân tích không gian khác. Tốc độ phản hồi được tối ưu hóa, giúp giảm đáng kể thời gian tính toán ngay cả khi xử lý hàng trăm điểm đầu – cuối trong một lần gọi API.

CÁCH TẠO MỘT YÊU CẦU DISTANCE MATRIX

Đầu tiên, bạn phải đăng ký tài khoản và tạo API key của Goong theo hướng dẫn chi tiết tại đây.

Hãy bắt đầu bằng cách nhập url vào trình duyệt web của bạn – sau đó thay thế YOUR_API_KEY bằng API key mà bạn đã tạo. Phản hồi về sẽ cho biết khoảng cách và thời lượng giữa các điểm gốc và đích đến được chỉ định.

URL: https://rsapi.goong.io/v2/distancematrix

Phương thức: GET

Tham số trong request truyền vào:

curl "https://rsapi.goong.io/v2/distancematrix?origins=20.981971,105.864323&destinations=21.031011,105.783206%7C21.022328,105.790480%7C21.016665,105.788774&vehicle=car&administrative_unit=new&api_key={YOUR_API_KEY}"
Tham số Mô tả Ví dụ
origins Tọa độ điểm xuất phát (hoặc nhiều điểm), theo định dạng lat,lng 20.981971,105.864323
destinations Tọa độ điểm đến (hoặc nhiều điểm), phân cách bằng dấu ` `
vehicle Loại phương tiện, bao gồm: ô tô (car), xe đạp (bike), taxi, xe tải (truck), hd (cho các phương tiện gọi xe). car
administrative_unit  Đây là tham số không bắt buộc. Để mặc định  hoặc administrative_unit= new sẽ trả về kết quả là đơn vị hành chính mới sau khi đã sáp nhập. Thêm tham số  administrative_unit=old sẽ trả về kết quả đơn vị hành chính cũ trước khi sáp nhập. new (mặc định)
api_key Mã khóa API do Goong cấp để xác thực thay bằng key của bạn

Tham số trong response trả về:

Tham số Mô tả Ví dụ
rows Là một mảng chứa các đối tượng, mỗi đối tượng đại diện cho một điểm bắt đầu. Bên trong mỗi row là trường elements, mô tả thông tin khoảng cách và thời gian đến các điểm đích tương ứng. 
 {
  “elements”: [
 {
  “distance”: {},
  “duration”: {},
  “status”: “OK”
 }
 ]
}
elements Mảng con nằm trong mỗi phần tử của rows. Mỗi element tương ứng với một cặp điểm bắt đầu → điểm kết thúc, chứa thông tin chi tiết: khoảng cách (distance), thời gian (duration) và trạng thái (status). 
"elements": [ 
{ "status": "OK",
 "duration": 
{ "text": "36 phút",
 "value": 2150 
},
status Trạng thái của từng cặp điểm. “OK” nghĩa là tính toán thành công. Có thể trả về “NOT_FOUND” hoặc “ZERO_RESULTS” nếu không tìm được tuyến đường phù hợp. ok
duration Thời gian di chuyển giữa hai điểm:
– text: hiển thị dạng người đọc (giờ, phút)
– value: đơn vị là giây, phục vụ tính toán		 
"duration": { 
"text": "35 phút", 
"value": 2089
distance Khoảng cách di chuyển giữa hai điểm:
– text: dạng hiển thị cho người dùng (km, m)
– value: đơn vị là mét		 
"distance": { 
"text": "15.1 km", 
"value": 15110