Snap To Roads API

Snap To Roads API hỗ trợ chuyển đổi các chuỗi tọa độ thô thành một lộ trình bám sát mạng lưới đường giao thông thực tế. API tự động nhận diện và căn chỉnh các điểm dữ liệu đầu vào vào đoạn đường phù hợp nhất, giúp loại bỏ các sai lệch hình học và nâng cao trải nghiệm hiển thị trực quan trên bản đồ.

Dịch vụ này đặc biệt hữu ích cho các bài toán theo dõi phương tiện, phát lại lịch sử hành trình, phân tích tuyến đường, logistics và quản lý đội xe.

---

Mục tiêu sử dụng

STT	UseCase	Mô tả tình huống	Cách giải quyết bằng Snap To Road API	Ví dụ cụ thể	Ứng dụng thực tế
1	Quản lý Đội xe (Fleet Management)	Xe tải di chuyển bị nhà cao tầng che khuất hoặc sóng yếu, gửi về các tọa độ rời rạc, nhảy lung tung (đi xuyên nhà, bay dưới sông).	1. Gom tập hợp các điểm vị trí thô (vĩ độ, kinh độ) thu được từ xe. 2. Truyền chuỗi tọa độ này vào tham số path của API. 3. API tự động quét mạng lưới đường giao thông xung quanh path để tìm các đoạn đường khớp nhất. 4. Hệ thống nhận về danh sách các điểm đã được nắn thẳng, loại bỏ hiện tượng xe nhảy vị trí sai thực tế.	Xe container chạy trên đường Nguyễn Văn Linh (TP.HCM) bị nhiễu tín hiệu báo đang đi dưới sông. Sau khi qua API, vị trí xe được đưa trở lại đúng làn đường xe tải.	Hệ thống giám sát hành trình (Dashboard) của các doanh nghiệp vận tải, logistics, xe container.
2	Tính khoảng cách để tính cước (Fare Calculation)	Tài xế đi qua nhiều ngõ ngách. Nếu chỉ nối các điểm thô bằng đường thẳng (đường chim bay), quãng đường sẽ bị ngắn hơn thực tế, gây thất thoát doanh thu.	1. Thu thập toàn bộ tọa độ thô của chuyến đi truyền vào tham số path. 2. Đặt cấu hình interpolate=true để yêu cầu API tự động bù (vẽ thêm) các điểm ẩn dọc theo đường cong ở những đoạn khoảng cách giữa 2 điểm gốc quá xa. 3. API tính toán và trả về lộ trình mượt mà bám khít theo từng khúc cua, ngã rẽ. 4. Hệ thống dùng danh sách điểm đã nội suy này để tính toán ra tổng số mét/km thực tế và nhân với đơn giá.	Một chuyến xe ôm công nghệ đi vào ngõ nhỏ ở Hà Nội. Đường chim bay đo được 3 km, nhưng sau khi API nắn mượt theo các ngã rẽ thực tế nhờ bật interpolate, khoảng cách chuẩn là 4.2 km.	Các ứng dụng đặt xe (Ride-hailing), ứng dụng giao đồ ăn, giao hàng nhanh (Grab, AhaMove, Xanh SM).
3	Phát lại hành trình (Trip Playback)	Khách hàng muốn xem lại lịch sử di chuyển. Nếu dùng tọa độ thô để vẽ, icon chiếc xe trên bản đồ sẽ bị phóng cắt góc qua các tòa nhà, giật cục.	1. Lấy danh sách tọa độ thô từ cơ sở dữ liệu truyền vào tham số path. 2. Bật cờ interpolate=true để API tự động điền thêm các điểm vị trí còn thiếu ở những đoạn mất sóng (đường hầm, cầu vượt). 3. API xử lý và trả về một chuỗi tọa độ mới dày đặc, liên tục và mượt mà dọc theo lòng đường. 4. Front-end dùng chuỗi tọa độ sạch này để làm hiệu ứng (animation) cho xe di chuyển tự nhiên.	Tính năng "Xem lại lộ trình đơn hàng" trên app TMĐT. Người mua nhìn thấy icon shipper di chuyển mượt mà qua từng con phố thay vì bị nhảy cóc từ phường này sang phường khác.	Tính năng lịch sử chuyến đi trong app định vị, app bảo hiểm xe hơi, app theo dõi vị trí người thân.
4	Theo dõi hoạt động Thể thao (Fitness Tracking)	Người dùng chạy bộ/đạp xe trong đô thị bị nhiễu định vị, đường vẽ kết quả bị răng cưa, cắt góc, dẫn đến tính sai vận tốc (Pace) trung bình.	1. Gửi chuỗi tọa độ vị trí thô của buổi tập vào tham số path. 2. Tùy thuộc vào tần suất ghi nhận điểm để quyết định bật hoặc tắt interpolate nhằm có đường vẽ tối ưu nhất. 3. API nắn các điểm răng cưa, đưa đường chạy về đúng vỉa hè hoặc tuyến đường tương ứng gần đó. 4. Hệ thống dùng lộ trình sạch đã nắn để tính toán chính xác chỉ số vận tốc (Pace) và hiển thị cho người dùng.	Người dùng chạy bộ quanh Hồ Gươm, tọa độ thô lúc lao xuống hồ, lúc đâm vào tòa nhà. Qua API, bản đồ hiển thị một đường tròn khép kín, bám vỉa hè cực đẹp để chia sẻ lên MXH.	Các ứng dụng tracking sức khỏe, thể thao như Strava, Garmin Connect, Nike Run Club, hoặc app của đồng hồ thông minh.

---

Base URL & Phiên bản

Hạng mục	Giá trị
Base URL	{{API_BASE_URL}}/api
Endpoint	{{API_BASE_URL}}/api/roads/v1/snap-to-roads

---

Xác thực (Authentication)

Snap To Roads API yêu cầu API key qua query parameter:

• Query param: apikey={YOUR_API_KEY}

---

Endpoint

API hỗ trợ hai phương thức cho cùng một logic Snap To Roads:

POST /roads/v1/snap-to-roads

Gửi path trong body JSON (khuyến nghị cho hành trình dài).

Loading...

Tham số yêu cầu (JSON body):

Tham số	Kiểu	Bắt buộc	Mô tả
path[].lon	number	Có	Kinh độ, trong khoảng [-180, 180].
path[].lat	number	Có	Vĩ độ, trong khoảng [-90, 90].
path	array<{lat,lon}> hoặc string	Có	Chuỗi điểm GPS theo thứ tự hành trình. Chấp nhận mảng {lat,lon} hoặc chuỗi "lat,lon|lat,lon|...".
interpolate	boolean	Không	Mặc định false. true → chèn thêm điểm nội suy bám đường (xem Hiểu về interpolate).

GET /roads/v1/snap-to-roads

Truyền path và interpolate qua query string. (tiện cho hành trình ngắn).

Loading...

Tham số yêu cầu (query params):

Tham số	Kiểu	Bắt buộc	Mô tả
apikey	string	Có	API key.
path	string	Có	Danh sách cặp lat,lon phân tách bằng |. VD: 10.822673,106.627857|10.823558,106.627857|...
interpolate	boolean	Không	Mặc định false. Chỉ nhận true/false.

Gợi ý chọn phương thức:

GET phù hợp cho các hành trình ngắn và mục đích thử nghiệm nhanh. Đối với hành trình dài, nên sử dụng POST để tránh giới hạn độ dài URL và đảm bảo toàn bộ danh sách tọa độ được truyền đầy đủ trong phần body của request.

---

Tham số truy vấn

Ràng buộc dữ liệu

Ràng buộc	Giá trị
Số điểm tối thiểu	2
Số điểm tối đa / request	100
Miền lat	[-90, 90]
Miền lon	[-180, 180]
Độ dài URL (GET)	Theo giới hạn của trình duyệt/HTTP — trace dài dùng POST

path (bắt buộc)

Chuỗi điểm GPS theo đúng thứ tự di chuyển. Hỗ trợ 2 dạng:

• Mảng [{ "lat": ..., "lon": ... }, ...] (chỉ POST).
• Chuỗi "lat,lon|lat,lon|..." (POST và GET).

Yêu cầu: tối thiểu 2 điểm, tối đa 100 điểm mỗi request; lat ∈ [-90, 90], lon ∈ [-180, 180].

interpolate (tuỳ chọn, mặc định là false)

• interpolate=false — chỉ nắn từng điểm đầu vào; mỗi điểm GPS tương ứng một điểm đầu ra.
• interpolate=true — nắn các điểm gốc và chèn thêm điểm dọc tim đường để mô tả hình học con đường đầy đủ hơn.

Điểm GPS thực tế thường thưa và không phản ánh khúc cua hay ngã rẽ. Khi cần vẽ lộ trình mượt bám đường, hãy bật interpolate. Khi chỉ cần chuẩn hóa tọa độ hoặc ghép điểm với mạng lưới đường, giữ interpolate=false.

Chọn chế độ interpolate

Đặc điểm	interpolate=false	interpolate=true
Điểm trả về	Một điểm đã snap cho mỗi điểm đầu vào	Điểm gốc đã snap cộng thêm điểm nội suy
Số lượng điểm	Xấp xỉ bằng số điểm đầu vào	Thường nhiều hơn số điểm đầu vào
originalIndex	Có trên mọi điểm trả về	Chỉ có trên điểm tương ứng đầu vào gốc
shape	Không trả về	Trả về dạng polyline đã mã hóa (polyline6)
Hình học lộ trình	Đơn giản	Bám sát hình học con đường hơn
Phù hợp cho	Chuẩn hóa GPS, phân tích, map matching	Hiển thị lộ trình, playback, vẽ đường mượt
Hiệu năng	Payload phản hồi nhỏ hơn	Payload phản hồi lớn hơn

---

Cấu trúc phản hồi

Root response

Trường	Kiểu	Mô tả
status	"OK" | "ERROR"	Trạng thái xử lý
data	object	Dữ liệu khi thành công (không có khi lỗi)
error	object	Thông tin lỗi khi thất bại (không có khi thành công)
licence	string	Luôn là © GTEL Maps

data

Trường	Kiểu	Mô tả
snappedPoints	array	Danh sách điểm đã nắn, theo thứ tự dọc tuyến
shape	string	Hình học tuyến đã nắn dạng encoded polyline (độ chính xác 6 — polyline6). Chỉ có khi interpolate=true.

snappedPoints[]

Trường	Kiểu	Mô tả
location	object	Tọa độ đã nắn về tim đường (WGS84): { latitude: number, longitude: number }.
originalIndex	integer	Chỉ số điểm gốc trong path đầu vào. Chỉ có với điểm gốc đã nắn.
way_id	integer	Định danh đoạn đường theo OpenStreetMap (way_id). Có thể vắng nếu không xác định được.

Phản hồi mẫu — interpolate=false

{
  "status": "OK",
  "data": {
    "snappedPoints": [
      {
        "location": { "lat": 10.77118, "lon": 106.69382 },
        "originalIndex": 0,
        "way_id": 123456789
      },
      {
        "location": { "lat": 10.77341, "lon": 106.69748 },
        "originalIndex": 1,
        "way_id": 123456789
      },
      {
        "location": { "lat": 10.77609, "lon": 106.70115 },
        "originalIndex": 2,
        "way_id": 987654321
      }
    ]
  },
  "licence": "© GTEL Maps"
}

Phản hồi mẫu — interpolate=true

{
  "status": "OK",
  "data": {
    "snappedPoints": [
      {
        "location": { "lat": 10.77118, "lon": 106.69382 },
        "originalIndex": 0,
        "way_id": 123456789
      },
      {
        "location": { "lat": 10.77201, "lon": 106.69510 },
        "way_id": 123456789
      },
      {
        "location": { "lat": 10.77341, "lon": 106.69748 },
        "originalIndex": 1,
        "way_id": 123456789
      },
      {
        "location": { "lat": 10.77480, "lon": 106.69930 },
        "way_id": 987654321
      },
      {
        "location": { "lat": 10.77609, "lon": 106.70115 },
        "originalIndex": 2,
        "way_id": 987654321
      }
    ],
    "shape": "ki{ohbU_ibE~pdA_ulL..."
  },
  "licence": "© GTEL Maps"
}

Lưu ý

Ví dụ trên minh hoạ interpolate=true: các điểm thứ 2, thứ 4 (không có originalIndex) là điểm nội suy nằm giữa các điểm gốc, và phản hồi có data.shape. Với interpolate=false, phản hồi không có data.shape và mọi điểm đều có originalIndex.

---

Ví dụ yêu cầu

POST — Snap To Roads với interpolate

curl -X POST "{{API_BASE_URL}}/api/roads/v1/snap-to-roads?apikey=YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "path": [
    { "lat": 10.7712, "lon": 106.6938 },
    { "lat": 10.7734, "lon": 106.6975 },
    { "lat": 10.7761, "lon": 106.7012 }
  ],
  "interpolate": true
}'

GET — Snap To Roads không interpolate

curl "{{API_BASE_URL}}/api/roads/v1/snap-to-roads?apikey=YOUR_API_KEY&path=10.7712,106.6938|10.7734,106.6975|10.7761,106.7012&interpolate=false"

---

Mã lỗi

Mã lỗi	HTTP Status	Mô tả
INVALID_REQUEST_DATA	400	Request không hợp lệ: thiếu/sai path, <2 hoặc >100 điểm, tọa độ ngoài miền, interpolate sai kiểu. Chi tiết ở error.fieldErrors.
UNPROCESSABLE_ENTITY	422	Không nắn được tuyến từ dữ liệu cung cấp (điểm quá xa mạng đường hoặc quá nhiễu).

INVALID_REQUEST_DATA

{
  "status": "ERROR",
  "error": {
    "code": "INVALID_REQUEST_DATA",
    "message": "Invalid request data",
    "fieldErrors": [
      {
        "field": "path",
        "message": "path must contain between 2 and 100 points"
      }
    ]
  },
  "licence": "© GTEL Maps"
}

UNPROCESSABLE_ENTITY

{
  "status": "ERROR",
  "error": {
    "code": "UNPROCESSABLE_ENTITY",
    "message": "Unable to snap one or more points to the road network"
  },
  "licence": "© GTEL Maps"
}

---

Ghi chú tích hợp

Chủ đề	Khuyến nghị
Khi bật interpolate	Khi cần vẽ polyline mượt trên bản đồ, playback hành trình, hoặc tính quãng đường bám đường chính xác.
Khi tắt interpolate	khi chỉ cần nắn từng điểm GPS về đường và giữ ánh xạ 1–1 theo originalIndex.
Dùng GET	Kiểm thử nhanh và cho hành trình ngắn
Dùng POST	Hành trình dài, payload phức tạp (tránh giới hạn độ dài URL)
Dùng way_id an toàn	Định danh đoạn đường theo OpenStreetMap, có thể thay đổi khi dữ liệu bản đồ được cập nhật — không nên dùng làm khóa lưu trữ vĩnh viễn.
Tính chất API	Stateless — mỗi request độc lập, không lưu trạng thái; có thể gọi song song.

---

Ví dụ

Xem demo Snap To Roads trong Maps SDKs. Tự vẽ tuyến trên bản đồ và quan sát cách Snap To Road nắn tuyến về mạng lưới đường thực tế. So sánh trực tiếp tuyến gốc (xanh dương) và tuyến đã nắn (đỏ), đồng thời bật/tắt Interpolate để xem sự khác biệt.

---