> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.hellotracks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Route Optimization

> Endpoint to optimize routes

## Optimize Route by Distance

This API call enables the optimization of an individual's daily route. It intelligently reorders jobs to
create an optimized route, focusing on minimizing travel distance while prioritizing high-priority jobs.
This optimization process is immediate, requiring no additional saving or editing actions.

### Key Features:

* **Priority and Distance Focused**: Prioritizes high-priority jobs while minimizing the overall travel distance.
* **Dynamic Route Start/End Points**:
  * Primarily, the worker's specified start/end locations are used.
  * If not set, the team's start location is considered.
  * In the absence of both, the first and last jobs of the day determine the route's endpoints.
* **Route Start Time**: Determined based on the worker's specified working hours.
* **Travel mode**: Determined based on the worker's travel mode setting (Car, Bicycle, Pedestrian, Truck, Van, Motorcycle).

### Note:

* Simple optimization (`solve: false`) optimizes primarily by route order and distance. Constraint-based solving (`solve: true`) can honor time windows, skills, capacity, and working-hours constraints.
* Route optimization naturally only works if all jobs are accessible via car or any vehicle.
* Also see: `/distributejobs` and `/autoassign` endpoints.

### REQUEST

```shell theme={null}
POST https://api.hellotracks.com/api/optimizeroute

{
	data: {
		day: 20221125,
		account: <worker-username-or-uid>,
		solve: <boolean> (optional),
		index: <number> (optional),
		count: <number> (optional),
		constraints: {
			working_hours: <boolean>,
			time_window: <boolean>,
			skills: <boolean>,
			capacity: <boolean>,
			max_jobs: <number>
		} (optional)
	}
}
```

<ParamField body="day" type="number" required>
  The date in number format: YYYYMMDD, e.g. 20221125 equals to Nov 25, 2022.
</ParamField>

<ParamField body="account" type="string" required>
  Worker's UID or username.
</ParamField>

<ParamField body="solve" type="boolean" default={false}>
  If `true`, uses advanced route solving with constraints (time windows, skills, capacity). If `false`, performs simple distance-based optimization. Solving mode may result in some jobs being unassigned if constraints cannot be satisfied.
</ParamField>

<ParamField body="index" type="number" optional>
  Starting index for partial route optimization. Use with `count` to optimize only a subset of jobs in the route.
</ParamField>

<ParamField body="count" type="number" optional>
  Number of jobs to include in partial route optimization, starting from `index`.
</ParamField>

<ParamField body="constraints" type="object" optional>
  Constraint configuration for route solving (only applies when `solve: true`):

  * `working_hours` (boolean, default: true): Respect worker's working hours
  * `time_window` (boolean, default: true): Honor job time windows
  * `skills` (boolean, default: true): Match required skills with worker capabilities
  * `capacity` (boolean, default: true): Consider pickup/dropoff capacity limits
  * `max_jobs` (number, default: 1000): Maximum number of jobs to process
</ParamField>

### RESPONSE

```shell theme={null}
{
	status: 0,
	jobs: [{<job1>}, {<job2>} ... ],
	original_order: ["<job_id_1>", "<job_id_2>" ... ],
	unassigned: ["<job_id_x>", "<job_id_y>" ... ],
	route_updated: <bool>,
	abort_reason: <string> (only present if solving failed),
	route_reason: <string> (only present if route calculation failed without an abort reason)
}
```

<ResponseField name="status" type="number" required>
  Status code. `0` indicates success, other values indicate errors (e.g., permission denied).
</ResponseField>

<ResponseField name="jobs" type="array" required>
  The newly arranged jobs representing the optimized route (includes full job objects).
</ResponseField>

<ResponseField name="original_order" type="array">
  Array of job IDs in their original order before optimization. Useful for implementing undo functionality.
</ResponseField>

<ResponseField name="unassigned" type="array">
  Array of job IDs that could not be assigned during route solving (only present when `solve: true`). These jobs couldn't be included due to constraint violations (e.g., time windows, capacity, skills mismatch).
</ResponseField>

<ResponseField name="route_updated" type="boolean" required>
  `true` if a route optimization was successfully calculated and applied.
</ResponseField>

<ResponseField name="abort_reason" type="string">
  Only present when route solving fails. Possible values:

  * `no_region`: No routing region available for the location
  * `impossible_route`: Route cannot be calculated with given constraints
  * `internal_error`: Server-side error during optimization
  * `input_error: <details>`: Invalid input parameters
  * `routing_error: <details>`: Error from routing service
</ResponseField>

<ResponseField name="route_reason" type="string">
  Present when route calculation fails and no `abort_reason` was returned.
</ResponseField>

### Permissions

Route optimization requires appropriate permissions:

* Administrators and company owners can always optimize routes
* Dispatchers can optimize routes for their team members
* Workers can optimize their own routes if the `workers_optimize_route` setting is enabled

### Caching & Throttling

* Recently optimized routes (within 3 hours) may be returned from cache for worker requests
* Reduces unnecessary recomputation when multiple optimization requests are made