> For the complete documentation index, see [llms.txt](https://navixy.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://navixy.com/docs/navixy-api/user-api/resources/field-service/task/route/optimize.md).

# Route optimization

Reorder a set of points so the total travel time between them is as small as possible.

This operation reorders a set of points so that the total travel time between them is as small as possible, which cuts transit time and cost on a multi-stop round.

It works on raw points rather than on a stored route, so there is no need to create a route and its checkpoints first. Send the points, and the response says what order to visit them in.

## API actions

API base path: `/task/route/points/optimize`.

***

*Required sub-user rights:* `task_update`.

## Optimize route points

> Return the order in which a set of points should be visited to minimise travel time. \*\*Creates nothing\*\*, so neither a route nor its checkpoints need to exist first.\
> \
> The suggested order respects each point's time window. Points with earlier windows get lower positions, and where windows overlap the order may vary to make the route as a whole more efficient.\
> \
> \*\*Limits: 2 to 49 points to visit, plus the start point, and 5000 km total distance.\*\* Sending one point returns error 7 with "The number of points must be in the range \[2..49]".\
> \
> \`result\` is the new order expressed as source indexes: the first entry says which of the points you sent should be visited first. So \`\[2, 0, 1]\` means visit the third point you sent, then the first, then the second.\
> \
> Requires the \`task\_update\` right.

```json
{"openapi":"3.1.0","info":{"title":"Navixy Platform API","version":"1.0.0"},"tags":[{"name":"Tasks","description":"Field service tasks: the places to visit, the routes and checkpoints they group into, the history of every change, and the forms field employees fill in. All resources under the /task/ path."}],"servers":[{"url":"https://api.eu.navixy.com/v2","description":"Navixy production server on European platform"},{"url":"https://api.us.navixy.com/v2","description":"Navixy production server on American platform"},{"url":"https://api.me.navixy.com/v2","description":"Navixy production server on Middle East platform"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","description":"Either a user session hash or an API key, with the \"NVX \" prefix, for example \"NVX 22eac1c27af4be7b9d04da2ce1af111b\". Obtain a session hash from the userAuth operation, or create an API key from the API keys operations. A small number of operations accept a session hash only and reject an API key with error code 4; each says so in its description.","name":"Authorization","in":"header"}},"responses":{"ResponseError":{"description":"Error response object","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always false."},"status":{"type":"object","description":"Error status. Present only when an error occurred.","properties":{"code":{"type":"integer","description":"An error code in this API, not an HTTP code."},"description":{"type":"string","description":"An error description."}}},"errors":{"type":"array","description":"Per-parameter detail, returned with validation failures such as error code 7. A parameter name here may be an internal field name rather than the documented parameter name.","items":{"type":"object","properties":{"parameter":{"type":"string","description":"Name of the parameter that failed validation."},"error":{"type":"string","description":"What was wrong with it."}}}}}}}}}}},"paths":{"/task/route/points/optimize":{"post":{"tags":["Tasks"],"summary":"Optimize route points","description":"Return the order in which a set of points should be visited to minimise travel time. **Creates nothing**, so neither a route nor its checkpoints need to exist first.\n\nThe suggested order respects each point's time window. Points with earlier windows get lower positions, and where windows overlap the order may vary to make the route as a whole more efficient.\n\n**Limits: 2 to 49 points to visit, plus the start point, and 5000 km total distance.** Sending one point returns error 7 with \"The number of points must be in the range [2..49]\".\n\n`result` is the new order expressed as source indexes: the first entry says which of the points you sent should be visited first. So `[2, 0, 1]` means visit the third point you sent, then the first, then the second.\n\nRequires the `task_update` right.","operationId":"taskRoutePointsOptimize","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"start_point":{"type":"object","description":"Where the performer departs from.","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."},"departure":{"type":"string","description":"Optional. When the performer departs."}}},"route_points":{"type":"array","description":"The points to visit, between 2 and 49 of them.","items":{"type":"object","properties":{"location":{"type":"object","description":"Where the point is.","properties":{"lat":{"type":"number","description":"Latitude."},"lng":{"type":"number","description":"Longitude."}}},"from":{"type":"string","description":"Start of the window in which this point can be visited."},"to":{"type":"string","description":"End of the window in which this point can be visited."}}},"minItems":2,"maxItems":49}},"required":["start_point","route_points"]}}}},"responses":{"200":{"description":"The suggested order","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true},"result":{"type":"array","description":"Indexes into `route_points`, in the order the points should be visited.","items":{"type":"integer"}}}}}}},"400":{"description":"Bad request. The response body carries the API-level error code in `status.code`. Validation failures also include an `errors` array naming each offending parameter.","$ref":"#/components/responses/ResponseError"},"403":{"description":"Error 210: the overall route distance is more than the 5000 km limit. Error 264: timeout not reached, meaning the call rate is too high.","$ref":"#/components/responses/ResponseError"},"default":{"$ref":"#/components/responses/ResponseError"}}}}}}
```

#### Errors

These errors come in addition to the [general error codes](/docs/navixy-api/general/errors.md#error-codes):

* 7 - Invalid parameters.
* 210 - Path distance exceeds the max distance limit - if the overal route distance is more than 5000 km.
* 264 - Timeout not reached - too high api call rate.

### How the result is read

```json
{
  "success": true,
  "result": [2, 0, 1] 
}
```

The `result` will return the order in which the points should be visited.

If for route points:

```
[
   {route_point_0}, // index in list = 0
   {route_point_1}, // index in list = 1
   {route_point_2}  // index in list = 2
]
```

this action returns: `[2, 0, 1]`

it means "change points order as following":

```
point at index 2 move to index 0,
point at index 0 move to index 1,
point at index 1 move to index 0
```

or with a more tangible example with 5 points. You have the next points to be reordered

```json
[
{"location": {"lat": 38.81673961922754,"lng": -77.15569496154785}, "from": "2024-03-19 00:00:00", "to": "2024-03-19 23:59:00"}, // it has index 0
{"location": {"lat": 38.82767290746902,"lng": -77.1445369720459}, "from": "2024-03-19 00:00:00", "to": "2024-03-19 23:59:00"}, // it has index 1
{"location": {"lat": 38.834760258479704,"lng": -77.14093208312988}, "from": "2024-03-19 00:00:00", "to": "2024-03-19 23:59:00"}, // this one with index 2
{"location": {"lat": 38.81583679562883,"lng": -77.14814186096191}, "from": "2024-03-19 00:00:00", "to": "2024-03-19 23:59:00"}, // this with index 3
{"location": {"lat": 38.81031929163279,"lng":7.15582370758057}, "from": "2024-03-19 00:00:00", "to": "2024-03-19 23:59:00"} // and this one has index 4
]
```

Sending those five points with a start point of `"lat": 38.81476676765485, "lng": -77.1608018875122`, the Navixy platform will reply to you with:

```json
{
  "result": [4,0,3,1,2],
  "success": true
}
```

So the optimized route with start point from "lat": 38.81476676765485, "lng": -77.1608018875122 should be:

```json
[
{"location": {"lat": 38.81031929163279,"lng":7.15582370758057}, "from": "2024-03-19 00:00:00", "to": "2024-03-19 23:59:00"}, // this one had index 4, now it is the first point to visit
{"location": {"lat": 38.81673961922754,"lng": -77.15569496154785}, "from": "2024-03-19 00:00:00", "to": "2024-03-19 23:59:00"}, // it had index 0, now it is the second point to visit
{"location": {"lat": 38.81583679562883,"lng": -77.14814186096191}, "from": "2024-03-19 00:00:00", "to": "2024-03-19 23:59:00"}, // this with index 3 becomes the third point to visit
{"location": {"lat": 38.82767290746902,"lng": -77.1445369720459}, "from": "2024-03-19 00:00:00", "to": "2024-03-19 23:59:00"}, // it had index 1, now it is the fourth point to visit
{"location": {"lat": 38.834760258479704,"lng": -77.14093208312988}, "from": "2024-03-19 00:00:00", "to": "2024-03-19 23:59:00"} // and this one with index 2, now it is the last fifth point to visit
]
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://navixy.com/docs/navixy-api/user-api/resources/field-service/task/route/optimize.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.