Back to Website
Guides
Dashboard

Directions API

Finds the fastest route between coordinates in the supplied order.

Suggest Edits

Try the Directions API demo

Request

Request Format

https://us1.locationiq.com/v1/directions/driving/{coordinates}?key=<YOUR_ACCESS_TOKEN>&alternatives={true|false|number}&steps={true|false}&geometries={polyline|polyline6|geojson}&overview={full|simplified|false}&annotations={true|false}

❗️

Coordinate Order

When using our Routing APIs, the order of coordinates should be entered as longitude,latitude instead of the typical latitude,longitude format.

Request Example

Query on London with three coordinates and no overview geometry returned:

https://us1.locationiq.com/v1/directions/driving/-0.127627,51.503355;-0.087199,51.509562;-0.076134,51.508037?key=<YOUR_ACCESS_TOKEN>&overview=false

Optional Parameters

🚧

Limitations

The Directions API is restricted to a maximum of 25 coordinates and a total distance limit of 10,000 KM (6213 miles). This distance limit is calculated using the straight-line distance (as the crow flies) rather than the actual routing distance. These limits can be increased on certain plans.

In addition to the general options the following options are supported for this service:

OptionValuesDescription
alternativestrue, false (default), or NumberSearch for alternative routes if available. Passing a number alternatives=n searches for up to n alternative routes.
stepstrue, false (default)Returned route steps for each route leg
annotationstrue, false (default), nodes, distance, duration, datasources, weight, speedReturns additional metadata for each coordinate along the route geometry.
geometriespolyline (default), polyline6, geojsonReturned route geometry format (influences overview and per step)
overviewsimplified (default), full, falseAdd overview geometry - either full or simplified according to highest zoom level it can be display on, or not at all.
continue_straightdefault (default), true, falseForces the route to keep going straight at waypoints constraining uturns there even if it would be faster. Default value depends on the profile.

Response

Response Example

Query on London with three coordinates and no overview geometry returned:

{
  "code": "ok",
  "waypoints": {
    "distance": 159.132824,
    "location": [
      -0.161547,
      51.522462
    ],
    "name": "Balcombe Street"
  },
  "routes": {
    "legs": {
      "steps": [],
      "weight": 22.7,
      "distance": 104.2,
      "summary": "",
      "duration": 24.8
    },
    "weight_name": "routability",
    "geometry": "k~myHtp^KeA_@aEACCW",
    "weight": 22.6,
    "distance": 104.8,
    "duration": 24.8
  }
}

Response Parameters

  • code if the request was successful Ok otherwise see the service dependent and general status codes.
  • waypoints: Array of Waypoint objects representing all waypoints in order:
  • routes: An array of Route objects, ordered by descending recommendation rank.

In case of error the following codes are supported in addition to the general ones:

TypeDescription
NoRouteNo route found.

All other properties might be undefined.

Updated about 1 year ago