GET /v1/directions

Returns a route between two points as a Google Directions API compatible response — routes[] → legs[] → steps[] with turn-by-turn instructions and encoded polylines — so clients built for Google/Goong can switch with minimal changes.

Required scope: routing:read

When no road route exists, the response still returns a drawable straight-line estimate with status: "ESTIMATED" (see 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"

Query parameters

Name	Required	Description
`origin`	yes	Start point as `lat,lng` (e.g. `21.0285,105.8542`).
`destination`	yes	End point as `lat,lng`.
`vehicle`	no	Routing profile. Supported: `motobike` (default). `car` is planned. Other values return `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": []
    }
  ]
}

Response fields

Field	Type	Description
`status`	string	`OK` (real road route), `ESTIMATED` (straight-line fallback).
`routes[].overview_polyline.points`	string	Encoded polyline (precision 5) of the whole route.
`routes[].bounds`	object	Bounding box (`northeast`/`southwest`). Omitted on fallback.
`routes[].legs[].distance`	object	`{ text, value }` — value in meters.
`routes[].legs[].duration`	object	`{ text, value }` — value in seconds.
`routes[].legs[].steps[].html_instructions`	string	Turn-by-turn instruction text.
`routes[].legs[].steps[].maneuver`	string	Google-style maneuver (`turn-left`, `turn-right`, `roundabout-right`, …). May be absent.
`routes[].legs[].steps[].polyline.points`	string	Encoded polyline for this step.

The encoded polylines use Google's Encoded Polyline Algorithm Format (precision 5) — decode them with any standard Google/Mapbox polyline decoder.

Fallback

If the routing engine can't connect the two points, GoGoDuk returns a straight-line estimate instead of an error, so your map always has a line to draw:

status is "ESTIMATED".
The leg has a single step whose geometry is the straight line origin → destination.
distance is the great-circle distance × a road-detour factor; duration is estimated from an average speed.

Render ESTIMATED routes differently (e.g. a dashed line) to signal it is not a real road route.

Common errors

400 INVALID_PARAMS — origin/destination not in lat,lng form.
400 INVALID_VEHICLE — unsupported vehicle value.
401 INVALID_API_KEY — key not recognized.
403 INSUFFICIENT_SCOPE — key is missing routing:read.
429 RATE_LIMIT_MINUTE — back off using the retry_after field.
503 ROUTING_UNAVAILABLE — routing is temporarily disabled.