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.


Request Format


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


Request Example

Round trip in London with three stops


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


Request Parameters

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

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:



Response Example

    "code": "Ok",
    "waypoints": [{
        "waypoint_index": 0,
        "trips_index": 0,
        "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,
        "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:

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

All other properties might be undefined.