Back to Website
Guides
Dashboard

Optimize API

Optimize API solves the Traveling Salesman Problem(TSP) using a greedy heuristic (farthest-insertion algorithm) for 10 or more waypoints and uses brute force for less than 10 waypoints. The returned path does not have to be the fastest path. As TSP is NP-hard it only returns an approximation.

Suggest Edits

Request

Request Format

🚧

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

❗️

Coordinate Order

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

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:

OptionValuesDescription
roundtriptrue (default), falseReturned route is a roundtrip (route returns to first location)
sourceany (default), firstReturned route starts at any or first coordinate
destinationany (default), lastReturned route ends at any or last coordinate
stepstrue, false (default)Returned route instructions for each trip
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, 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:

roundtripsourcedestinationsupported
truefirstlastyes
truefirstanyyes
trueanylastyes
trueanyanyyes
falsefirstlastyes
falsefirstanyyes
falseanylastyes
falseanyanyno

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:

TypeDescription
NoTripsNo trips found because input coordinates are not connected.
NotImplementedThis request is not supported

All other properties might be undefined.

Updated about 1 month ago