--- title: "Directions Service" method: GET path: "/directions/{profile}/{coordinates}" tags: ["Routing"] --- # Directions Service `GET /directions/{profile}/{coordinates}` Finds the fastest route between coordinates in the supplied order. ## Query parameters - `bearings` string - `radiuses` string - `hints` string - `alternatives` number - `steps` string - `annotations` string - `geometries` string - `overview` string - `continue_straight` string - `waypoints` string ## Response `200` OK - DirectionsDirections - `code` string — If the request was successful `Ok` otherwise see the service dependent and general status codes. - `waypoints` object[] — Object used to describe waypoint on a route. - `hint` string — The distance, in meters, from the input coordinate to the snapped coordinate. - `distance` number — The distance, in meters, from the input coordinate to the snapped coordinate. - `name` string — Unique internal identifier of the segment (ephemeral, not constant over data updates) This can be used on subsequent request to significantly speed up the query and to connect multiple services. E.g. you can use the `hint` value obtained by the `nearest` query as `hint` values for `route` inputs. - `location` number[] — Array that contains the `[longitude, latitude]` pair of the snapped coordinate. - `routes` RouteRouting[] — Represents a route through (potentially multiple) waypoints. - `legs` object[] — Represents a route between two waypoints. - `steps` object[] — A step consists of a maneuver such as a turn or merge, followed by a distance of travel along a single way to the subsequent step. Depends on the `steps` parameter. | steps | | |--------------|-----------------------------------------------------------------------| | true | array of `RouteStep` objects describing the turn-by-turn instructions | | false | empty array | - `intersections` object — An intersection gives a full representation of any cross-way the path passes bay. For every step, the very first intersection (`intersections[0]`) corresponds to the location of the StepManeuver. Further intersections are listed for every cross-way until the next turn instruction. - `location` number[] — A `[longitude, latitude]` pair describing the location of the turn. - `in` number — index into bearings/entry array. Used to calculate the bearing just before the turn. Namely, the clockwise angle from true north to the direction of travel immediately before the maneuver/passing the intersection. Bearings are given relative to the intersection. To get the bearing in the direction of driving, the bearing has to be rotated by a value of 180. The value is not supplied for `depart` maneuvers. - `out` number — index into the bearings/entry array. Used to extract the bearing just after the turn. Namely, The clockwise angle from true north to the direction of travel immediately after the maneuver/passing the intersection. The value is not supplied for `arrive` maneuvers. - `bearings` number — A list of bearing values (e.g. [0,90,180,270]) that are available at the intersection. The bearings describe all available roads at the intersection. Values are between 0-359 (0=true north) - `entry` string — A list of entry flags, corresponding in a 1:1 relationship to the bearings. A value of `true` indicates that the respective road could be entered on a valid route. `false` indicates that the turn onto the respective road would violate a restriction. - `classes` string[] — An array of strings signifying the classes (as specified in the profile) of the road exiting the intersection. - `lanes` object[] — A `Lane` represents a turn lane at the corresponding turn location. - `indications` string — An indication (e.g. marking on the road) specifying the turn lane. A road can have multiple indications (e.g. an arrow pointing straight and left). The indications are given in an array, each containing one of the following types. Further indications might be added on without an API version change. | `value` | Description | |------------------------|---------------------------------------------------------------------------------------------------------------------------| | `none` | No dedicated indication is shown. | | `uturn` | An indication signaling the possibility to reverse (i.e. fully bend arrow). | | `sharp right` | An indication indicating a sharp right turn (i.e. strongly bend arrow). | | `right` | An indication indicating a right turn (i.e. bend arrow). | | `slight right` | An indication indicating a slight right turn (i.e. slightly bend arrow). | | `straight` | No dedicated indication is shown (i.e. straight arrow). | | `slight left` | An indication indicating a slight left turn (i.e. slightly bend arrow). | | `left` | An indication indicating a left turn (i.e. bend arrow). | | `sharp left` | An indication indicating a sharp left turn (i.e. strongly bend arrow). | - `valid` string — A boolean flag (represented as `string`) indicating whether the lane is a valid choice in the current maneuver. - `driving_side` string — The legal driving side at the location for this step. Either `left` or `right`. - `geometry` string — The unsimplified geometry of the route segment, depending on the `geometries` parameter. | `geometry` | | |------------|--------------------------------------------------------------------| | polyline | [polyline](https://www.npmjs.com/package/polyline) with precision 5 in [latitude,longitude] encoding | | polyline6 | [polyline](https://www.npmjs.com/package/polyline) with precision 6 in [latitude,longitude] encoding | | geojson | [GeoJSON `LineString`](http://geojson.org/geojson-spec.html#linestring) | - `duration` number — The estimated travel time, in `float` number of seconds. - `distance` number — The distance of travel from the maneuver to the subsequent step, in `float` meters. - `name` string — The name of the way along which travel proceeds. - `weight` number — The calculated weight of the step. - `mode` string — A string signifying the mode of transportation. - `maneuver` object[] — A `StepManeuver` object representing the maneuver. - `bearing_after` number — The clockwise angle from true north to the direction of travel immediately after the maneuver. Range 0-359. - `location` number[] — A `[longitude, latitude]` pair describing the location of the turn. - `type` string — A string indicating the type of maneuver. **new identifiers might be introduced without API change** | `type` | Description | |------------------|--------------------------------------------------------------| | `turn` | a basic turn into direction of the `modifier` | | `new name` | no turn is taken/possible, but the road name changes. The road can take a turn itself, following `modifier`. | | `depart` | indicates the departure of the leg | | `arrive` | indicates the destination of the leg | | `merge` | merge onto a street (e.g. getting on the highway from a ramp, the `modifier specifies the direction of the merge`) | | `ramp` | **Deprecated**. Replaced by `on_ramp` and `off_ramp`. | | `on ramp` | take a ramp to enter a highway (direction given my `modifier`) | | `off ramp` | take a ramp to exit a highway (direction given my `modifier`) | | `fork` | take the left/right side at a fork depending on `modifier` | | `end of road` | road ends in a T intersection turn in direction of `modifier`| | `use lane` | **Deprecated** replaced by lanes on all intersection entries | | `continue` | Turn in direction of `modifier` to stay on the same road | | `roundabout` | traverse roundabout, if the route leaves the roundabout there will be an additional property `exit` for exit counting. The modifier specifies the direction of entering the roundabout. | | `rotary` | a traffic circle. While very similar to a larger version of a roundabout, it does not necessarily follow roundabout rules for right of way. It can offer `rotary_name` and/or `rotary_pronunciation` parameters (located in the RouteStep object) in addition to the `exit` parameter (located on the StepManeuver object). | | `roundabout turn`| Describes a turn at a small roundabout that should be treated as normal turn. The `modifier` indicates the turn direction. Example instruction: `At the roundabout turn left`. | | `notification` | not an actual turn but a change in the driving conditions. For example the travel mode or classes. If the road takes a turn itself, the `modifier` describes the direction | | `exit roundabout`| Describes a maneuver exiting a roundabout (usually preceded by a `roundabout` instruction) | | `exit rotary` | Describes the maneuver exiting a rotary (large named roundabout) | - `bearing_before` number — he clockwise angle from true north to the direction of travel immediately before the maneuver. Range 0-359. - `modifier` string — An optional `string` indicating the direction change of the maneuver. | `modifier` | Description | |-------------------|-------------------------------------------| | `uturn` | indicates reversal of direction | | `sharp right` | a sharp right turn | | `right` | a normal turn to the right | | `slight right` | a slight turn to the right | | `straight` | no relevant change in direction | | `slight left` | a slight turn to the left | | `left` | a normal turn to the left | | `sharp left` | a sharp turn to the left | The list of turns without a modifier is limited to: `depart/arrive`. If the source/target location is close enough to the `depart/arrive` location, no modifier will be given. The meaning depends on the `type` property. | `type` | Description | |------------------------|---------------------------------------------------------------------------------------------------------------------------| | `turn` | `modifier` indicates the change in direction accomplished through the turn | | `depart`/`arrive` | `modifier` indicates the position of departure point and arrival point in relation to the current direction of travel | - `exit` An optional `integer` indicating number of the exit to take. The property exists for the `roundabout` / `rotary` property: Number of the roundabout exit to take. If exit is `undefined` the destination is on the roundabout. New properties (potentially depending on `type`) may be introduced in the future without an API version change. - `ref` string — A reference number or code for the way. Optionally included, if ref data is available for the given way. - `weight` number — The calculated weight of the route leg. - `distance` number — The distance traveled by this route leg, in `float` meters. - `annotations` object — Additional details about each coordinate along the route geometry, with fine-grained information about each segment or node id. | annotations | | |--------------|-------------------------------------------------------------------------------| | true | An `Annotation` object containing node ids, durations, distances and weights. | | false | `undefined` | - `speed` number[] — Convenience field, calculation of `distance / duration` rounded to one decimal place. - `metadata` object — Metadata related to other annotations. - `datasource_names` string[] — The names of the datasources used for the speed between each pair of coordinates. `lua profile` is the default profile, other values are the filenames supplied via `--segment-speed-file` to `osrm-contract` or `osrm-customize`. - `nodes` number[] — The OSM node ID for each coordinate along the route, excluding the first/last user-supplied coordinates. - `duration` number[] — The duration between each pair of coordinates, in seconds. Does not include the duration of any turns. - `distance` number[] — The distance, in meters, between each pair of coordinates. - `weight` number[] — The weights between each pair of coordinates. Does not include any turn costs. - `datasources` number[] — The index of the datasource for the speed between each pair of coordinates. `0` is the default profile, other values are supplied via `--segment-speed-file` to `osrm-contract` or `osrm-customize`. String-like names are in the `metadata.datasource_names` array. - `summary` string — Summary of the route taken as `string`. Depends on the `summary` parameter. | summary | | |--------------|-----------------------------------------------------------------------| | true | Names of the two major roads used. Can be empty if route is too short.| | false | empty `string` | - `duration` string — The estimated travel time, in `float` number of seconds. - `weight_name` string - `geometry` string - `weight` number - `distance` number - `duration` number ## Other responses - `400` — Bad Request - `401` — Unauthorized - `403` — The request has been made from an unauthorized domain. - `404` — No location or places were found for the given input - `429` — Request exceeded the rate-limits set on your account - `500` — Internal Server Error --- [API](https://skmtc.dev/locationiq/apis/locationiq-api-reference.md) · [All operations](https://skmtc.dev/locationiq/apis/locationiq-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/locationiq/locationiq-api-reference/revisions/62f2eab3d1ff/schema)