Request

👍

Routing API Syntax

All Routing HTTP requests use a common structure. The following syntax applies to all services, except as noted.

Request Format

Requests can be sent to any of the following endpoints

Region 1: US

https://us1.locationiq.com/v1/{service}/{profile}/{coordinates}?key=<YOUR_ACCESS_TOKEN>&option=value&option=value

Region 2: Europe

https://eu1.locationiq.com/v1/{service}/{profile}/{coordinates}?key=<YOUR_ACCESS_TOKEN>&option=value&option=value

Parameters

❗️

Coordinate Order

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

Passing any option=value is optional. polyline follows Google's polyline format with precision 5 by default and can be generated using this package.

📘

List of all input parameters available on the API Reference page

Request options

Where the elements follow the following format:

Example: 2nd location use the default value for option:

{option}={element};;{element}

The number of elements must match exactly the number of locations (except for generate_hints and exclude). If you don't want to pass a value but instead use the default you can pass an empty element.

Response

Response Codes

Every response object has a code property containing one of the strings below or a service dependent code:

Response Objects

📘

List of all output parameters & Objects available on the API Reference page

Route object

Represents a route through (potentially multiple) waypoints.

Route object example with three input coordinates, geometry=geojson, steps=false:

{
  "distance": 90.0,
  "duration": 300.0,
  "weight": 300.0,
  "weight_name": "duration",
  "geometry": {"type": "LineString", "coordinates": [[120.0, 10.0], [120.1, 10.0], [120.2, 10.0], [120.3, 10.0]]},
  "legs": [
    {
      "distance": 30.0,
      "duration": 100.0,
      "steps": []
    },
    {
      "distance": 60.0,
      "duration": 200.0,
      "steps": []
    }
  ]
}

RouteLeg object

Represents a route between two waypoints.

RouteLeg object example with steps=false and annotations=true:

{
  "distance": 30.0,
  "duration": 100.0,
  "weight": 100.0,
  "steps": [],
  "annotation": {
    "distance": [5,5,10,5,5],
    "duration": [15,15,40,15,15],
    "datasources": [1,0,0,0,1],
    "metadata": { "datasource_names": ["traffic","lua profile","lua profile","lua profile","traffic"] },
    "nodes": [49772551,49772552,49786799,49786800,49786801,49786802],
    "speed": [0.3, 0.3, 0.3, 0.3, 0.3]
  }
}

Annotation object

Annotation of the whole route leg with fine-grained information about each segment or node id.

{
  "distance": [5,5,10,5,5],
  "duration": [15,15,40,15,15],
  "datasources": [1,0,0,0,1],
  "metadata": { "datasource_names": ["traffic","lua profile","lua profile","lua profile","traffic"] },
  "nodes": [49772551,49772552,49786799,49786800,49786801,49786802],
  "weight": [15,15,40,15,15]
}

RouteStep 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.

{
   "geometry" : "{lu_IypwpAVrAvAdI",
   "mode" : "driving",
   "duration" : 15.6,
   "weight" : 15.6,
   "intersections" : [
      {  "bearings" : [ 10, 92, 184, 270 ],
         "lanes" : [
            { "indications" : [ "left", "straight" ],
               "valid" : "false" },
            { "valid" : "true",
               "indications" : [ "right" ] }
         ],
         "out" : 2,
         "in" : 3,
         "entry" : [ "true", "true", "true", "false" ],
         "location" : [ 13.39677, 52.54366 ]
      },
      {  "out" : 1,
         "lanes" : [
            { "indications" : [ "straight" ],
               "valid" : "true" },
            { "indications" : [ "right" ],
               "valid" : "false" }
         ],
         "bearings" : [ 60, 240, 330 ],
         "in" : 0,
         "entry" : [ "false", "true", "true" ],
         "location" : [ 13.394718, 52.543096 ]
      }
   ],
   "name" : "Lortzingstraße",
   "distance" : 152.3,
   "maneuver" : {
      "modifier" : "right",
      "type" : "turn"
   }
}

StepManeuver object

Details about a specific maneuver or action that a user should take at a particular step along the route.

{
  "location": [-73.985726, 40.748817],
  "instruction": "Turn left onto Main Street",
  "type": "turn",
  "modifier": "left",
  "exit": null
}

Lane object

A Lane represents a turn lane at the corresponding turn location.

{
    "indications": ["left", "straight"],
    "valid": "false"
}

Intersection 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":[13.394718,52.543096],
    "in":0,
    "out":2,
    "bearings":[60,150,240,330],
    "entry":["false","true","true","true"],
    "classes": ["toll", "restricted"],
    "lanes":{
        "indications": ["left", "straight"],
        "valid": "false"
    }
}

Waypoint object

Object used to describe waypoint on a route.

{
   "hint" : "KSoKADRYroqUBAEAEAAAABkAAAAGAAAAAAAAABhnCQCLtwAA_0vMAKlYIQM8TMwArVghAwEAAQH1a66g",
   "distance" : 4.152629,
   "name" : "Friedrichstraße",
   "location" : [
      13.388799,
      52.517033
   ]
}

🚧

Authentication Errors

Authentication error messages are listed in the errors section.