GET /v1/directions

Trả về tuyến đường giữa hai điểm theo định dạng tương thích Google Directions API — routes[] → legs[] → steps[] kèm hướng dẫn rẽ từng bước và polyline đã mã hoá — nên client viết cho Google/Goong có thể chuyển sang với rất ít thay đổi.

Scope yêu cầu: routing:read

Khi không có tuyến đường thật, response vẫn trả về một đường ước lượng (đường thẳng) vẽ được, với status: "ESTIMATED" (xem Fallback).

Request

GET /v1/directions?origin=21.0285,105.8542&destination=21.2212,105.8072&vehicle=motobike
X-API-Key: gdk_live_xxxxxxxxxxxxxxxxxxxxxxxx

curl -G "https://api.gogoduk.com/v1/directions" \
-H "X-API-Key: $GOGODUK_API_KEY" \
--data-urlencode "origin=21.0285,105.8542" \
--data-urlencode "destination=21.2212,105.8072" \
--data-urlencode "vehicle=motobike"

Tham số query

Tên	Bắt buộc	Mô tả
`origin`	có	Điểm đi dạng `lat,lng` (vd `21.0285,105.8542`).
`destination`	có	Điểm đến dạng `lat,lng`.
`vehicle`	không	Loại phương tiện. Hỗ trợ: `motobike` (mặc định). `car` sẽ có sau. Giá trị khác trả `400`.

Response

{
  "status": "OK",
  "routes": [
    {
      "summary": "",
      "legs": [
        {
          "distance": { "text": "5.7 km", "value": 5704.1 },
          "duration": { "text": "9 phút", "value": 511.2 },
          "start_location": { "lat": 21.0285, "lng": 105.8542 },
          "end_location": { "lat": 21.2212, "lng": 105.8072 },
          "steps": [
            {
              "distance": { "text": "243 m", "value": 243.4 },
              "duration": { "text": "<1 phút", "value": 21 },
              "start_location": { "lat": 21.0285, "lng": 105.8542 },
              "end_location": { "lat": 21.0298, "lng": 105.8565 },
              "html_instructions": "Head northwest on Pasteur",
              "maneuver": "turn-right",
              "polyline": { "points": "suw`Aq{fjSOF{Bx@..." },
              "travel_mode": "DRIVING"
            }
          ]
        }
      ],
      "overview_polyline": { "points": "suw`Aq{fjS..." },
      "bounds": {
        "northeast": { "lat": 21.238, "lng": 105.8544 },
        "southwest": { "lat": 21.0288, "lng": 105.7984 }
      },
      "warnings": [],
      "waypoint_order": []
    }
  ]
}

Trường response

Trường	Kiểu	Mô tả
`status`	string	`OK` (tuyến đường thật), `ESTIMATED` (đường thẳng ước lượng).
`routes[].overview_polyline.points`	string	Polyline mã hoá (precision 5) của toàn tuyến.
`routes[].bounds`	object	Khung bao (`northeast`/`southwest`). Bỏ qua khi fallback.
`routes[].legs[].distance`	object	`{ text, value }` — value tính bằng mét.
`routes[].legs[].duration`	object	`{ text, value }` — value tính bằng giây.
`routes[].legs[].steps[].html_instructions`	string	Hướng dẫn rẽ từng bước.
`routes[].legs[].steps[].maneuver`	string	Mã rẽ kiểu Google (`turn-left`, `turn-right`, `roundabout-right`, …). Có thể vắng.
`routes[].legs[].steps[].polyline.points`	string	Polyline mã hoá của riêng bước này.

Các polyline dùng Encoded Polyline Algorithm Format của Google (precision 5) — giải mã bằng bất kỳ thư viện decoder Google/Mapbox nào.

Fallback

Nếu engine định tuyến không nối được hai điểm, GoGoDuk trả về đường ước lượng (đường thẳng) thay vì lỗi, để bản đồ luôn có đường để vẽ:

status là "ESTIMATED".
Leg chỉ có một step với hình học là đường thẳng origin → destination.
distance là khoảng cách chim bay × hệ số đường bộ; duration ước lượng theo vận tốc trung bình.

Nên vẽ tuyến ESTIMATED khác đi (vd nét đứt) để báo cho người dùng đây không phải tuyến đường thật.

Lỗi thường gặp

400 INVALID_PARAMS — origin/destination không đúng dạng lat,lng.
400 INVALID_VEHICLE — giá trị vehicle không hỗ trợ.
401 INVALID_API_KEY — key không hợp lệ.
403 INSUFFICIENT_SCOPE — key thiếu scope routing:read.
429 RATE_LIMIT_MINUTE — chờ theo trường retry_after.
503 ROUTING_UNAVAILABLE — định tuyến tạm thời bị tắt.