Skip to main content

​
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. If the date is set to today, workers will be promptly notified of their updated job order.

​
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:

  • Currently, this route optimization does not support specific time windows for jobs or locations.
  • Route optimization naturally only works if all jobs are accessible via car or any vehicle.
  • Also see: /distributejobs and /autoassign endpoints.

​
REQUEST

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)
	}
}
​
day
number
required
The date in number format: YYYYMMDD, e.g. 20221125 equals to Nov 25, 2022.
​
account
string
required
Worker’s UID or username.
​
solve
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.
​
index
number
Starting index for partial route optimization. Use with count to optimize only a subset of jobs in the route.
​
count
number
Number of jobs to include in partial route optimization, starting from index.
​
constraints
object
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

​
RESPONSE

{
	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)
}
​
status
number
required
Status code. 0 indicates success, other values indicate errors (e.g., permission denied).
​
jobs
array
required
The newly arranged jobs representing the optimized route (includes full job objects).
​
original_order
array
Array of job IDs in their original order before optimization. Useful for implementing undo functionality.
​
unassigned
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).
​
route_updated
boolean
required
true if a route optimization was successfully calculated and applied.
​
abort_reason
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

​
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