Optimize API

Request

Request Format

🚧
Note that all input coordinates have to be connected for the optimize service to work.

https://us1.locationiq.com/v1/optimize/driving/{coordinates}?key=<YOUR_ACCESS_TOKEN>&roundtrip={true|false}&source{any|first}&destination{any|last}&steps={true|false}&geometries={polyline|polyline6|geojson}&overview={simplified|full|false}&annotations={true|false}

Request Example

Round trip in London with three stops

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

Round trip in London with four stops, starting at the first stop, ending at the last:

https://us1.locationiq.com/v1/optimize/driving/-0.127627,51.503355;-0.087199,51.509562;-0.076134,51.508037;-0.142001,51.501284?key=<YOUR_ACCESS_TOKEN>&source=first&destination=last

Request Parameters

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

Option	Values	Description
roundtrip	`true` (default), `false`	Returned route is a roundtrip (route returns to first location)
source	`any` (default), `first`	Returned route starts at `any` or `first` coordinate
destination	`any` (default), `last`	Returned route ends at `any` or `last` coordinate
steps	`true`, `false` (default)	Returned route instructions for each trip
annotations	`true`, `false` (default), `nodes`, `distance`, `duration`, `datasources`, `weight`, `speed`	Returns additional metadata for each coordinate along the route geometry.
geometries	`polyline` (default), `polyline6`, `geojson`	Returned route geometry format (influences overview and per step)
overview	`simplified` (default), `full`, `false`	Add overview geometry either full, simplified according to highest zoom level it could be display on, or not at all.

Fixing Start and End Points

It is possible to explicitly set the start or end coordinate of the trip.

When source is set to first, the first coordinate is used as starting coordinate of the trip in the output. When destination is set to last, the last coordinate will be used as destination of the trip in the returned output. If you specify any, any of the coordinates can be used as the first or last coordinate in the output.

However, if source=any&destination=any the returned round-trip will still start at the first input coordinate by default.

Currently, not all combinations of roundtrip, source and destination are supported.
Right now, the following combinations are possible:

roundtrip	source	destination	supported
true	first	last	yes
true	first	any	yes
true	any	last	yes
true	any	any	yes
false	first	last	yes
false	first	any	no
false	any	last	no
false	any	any	no

Response

Response Example

{
    "code": "Ok",
    "waypoints": [{
        "waypoint_index": 0,
        "trips_index": 0,
        "hint": "dRJAiW_vt4sOAAAAAAAAAAAAAAAAAAAA1kBzQQAAAAAAAAAAAAAAAA4AAAAAAAAAAAAAAAAAAAAIFwEAIhL-_zzgEQN1Df7_--ARAwAAzxB42O4j",
        "distance": 85.752389,
        "location": [-0.12643, 51.503164],
        "name": "Downing Street"
    }, {
        "waypoint_index": 1,
        "trips_index": 0,
        "hint": "BdAMgP___38BAAAAKAAAAFsAAAC7AAAAdwJqP1dc30EhbYFCWlnxQgEAAAAoAAAAWwAAALsAAAAIFwEAYKv-_zr5EQNhq_7_OvkRAwQA3wB42O4j",
        "distance": 0.069405,
        "location": [-0.0872, 51.509562],
        "name": "King William Street"
    }, {
        "waypoint_index": 2,
        "trips_index": 0,
        "hint": "kXleipl5XooAAAAAFgAAAAAAAAAAAAAAAAAAAOHmE0EAAAAAAAAAAAAAAAAWAAAAAAAAAAAAAAAIFwEAlNn-_zzwEQOa1v7_RfMRAwAAbwt42O4j",
        "distance": 101.342282,
        "location": [-0.075372, 51.50726],
        "name": ""
    }],
    "trips": [{
        "legs": [{
            "steps": [],
            "weight": 529,
            "distance": 3826.2,
            "summary": "",
            "duration": 529
        }, {
            "steps": [],
            "weight": 3505.1,
            "distance": 1274.1,
            "summary": "",
            "duration": 228.4
        }, {
            "steps": [],
            "weight": 3783.4,
            "distance": 4260.8,
            "summary": "",
            "duration": 509.1
        }],
        "weight_name": "routability",
        "geometry": "wejyHduWAsApLXh@_t@|@uD{@mDzJkThBsIqDyrAXqAeL{U{PgMaJ_MeVwHmGwBhAuUbEoQrBbFnCeMpB_AhCsRs@Ir@HiCrRqB~@aClNsC`e@cClP{C`_@N~iBfBbUpEjSdDdGtDhDnHbFpHvB{@`Kd@dF|Hq@@rA",
        "weight": 7817.5,
        "distance": 9361.1,
        "duration": 1266.5
    }]
}

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 input order. Each Waypoint object has the following additional properties:
- trips_index: Index to trips of the sub-trip the point was matched to.
- waypoint_index: Index of the point in the trip.
trips: An array of Route objects that assemble the trace.

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

Type	Description
`NoTrips`	No trips found because input coordinates are not connected.
`NotImplemented`	This request is not supported

All other properties might be undefined.