General Options
API | Description |
---|---|
Directions API | Generates a route connecting provided coordinates, allowing for up to 25 coordinates in a single request. The route follows the sequence of input coordinates to create the path. |
Optimize API | Generates the most optimized route for a set of coordinates, without considering the order of the input coordinates. |
Matrix API | Computes duration of the fastest route between all pairs of supplied coordinates |
Map Matching API | Normalize GPS points by snapping them to roads |
Nearest API | Snaps a coordinate to the street network and returns the nearest matches. |
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.
Parameter | Description |
---|---|
service | One of the following values: directions , matching , matrix , nearest , optimize |
profile | Mode of transportation. Only driving is supported at the moment. |
coordinates | String of format {longitude},{latitude};{longitude},{latitude}[;{longitude},{latitude} ...] or polyline({polyline}) or polyline6({polyline6}) . You can send up to a maximum of 25 coordinate pairs per request (except Nearest API where coordinates only supports a single {longitude},{latitude} entry). This limit can be increased on certain plans. |
key | Your public access token |
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
Option | Values | Description |
---|---|---|
bearings | {bearing};{bearing}[;{bearing} ...] | Limits the search to segments with given bearing in degrees towards true north in clockwise direction. |
radiuses | {radius};{radius}[;{radius} ...] | Limits the search to given radius in meters. |
generate_hints | true (default), false | Adds a Hint to the response which can be used in subsequent requests, see hints parameter. |
hints | {hint};{hint}[;{hint} ...] | Hint from previous request to derive position in street network. |
approaches | {approach};{approach}[;{approach} ...] | Keep waypoints on curb side. |
exclude | {class}[,{class}] | Additive list of classes to avoid, order does not matter. E.g. exclude=ferry,toll or exclude=motorway |
Where the elements follow the following format:
Element | Values |
---|---|
bearing | {value},{range} integer 0 .. 360,integer 0 .. 180 |
radius | double >= 0 or unlimited (default) |
hint | Base64 string |
approach | curb or unrestricted (default) |
class | A class name determined by the profile or none. |
{option} | {element};{element}[;{element} ... ] |
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:
Type | HTTP Response Code | Description |
---|---|---|
Ok | 200 | Request could be processed as expected. |
InvalidUrl | 400 | URL string is invalid. |
InvalidService | 400 | Service name is invalid. |
InvalidOptions | 400 | Options are invalid. |
InvalidQuery | 400 | The query string is syntactically malformed. |
InvalidValue | 400 | The successfully parsed query parameters are invalid. |
NoSegment | 404 | One of the supplied input coordinates could not snap to street segment. |
TooBig | 400 | The request size violates one of the service specific request size restrictions. |
NoMatch | 404 | No matchings found. |
Response Objects
List of all output parameters & Objects available on the API Reference page
Object | Description |
---|---|
Route object | Represents a route through (potentially multiple) waypoints. |
RouteLeg object | Represents a route between two waypoints |
Annotation object | Annotation of the whole route leg with fine-grained information about each segment or node id. |
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. |
StepManeuver object | Details about a specific maneuver or action that a user should take at a particular step along the route. |
Lane object | A Lane represents a turn lane at the corresponding turn location. |
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. |
Waypoint object | Object used to describe waypoint on a route. |
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
andannotations=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.
Updated 7 months ago