Route Optimization
curl --request POST \
--url https://api.hellotracks.com/api/optimizeroute \
--header 'API-Key: <api-key>' \
--header 'Content-Type: application/json' \
--data '
{
"day": 123,
"account": "<string>",
"solve": true,
"index": 123,
"count": 123,
"constraints": {}
}
'import requests
url = "https://api.hellotracks.com/api/optimizeroute"
payload = {
"day": 123,
"account": "<string>",
"solve": True,
"index": 123,
"count": 123,
"constraints": {}
}
headers = {
"API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
day: 123,
account: '<string>',
solve: true,
index: 123,
count: 123,
constraints: {}
})
};
fetch('https://api.hellotracks.com/api/optimizeroute', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.hellotracks.com/api/optimizeroute",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'day' => 123,
'account' => '<string>',
'solve' => true,
'index' => 123,
'count' => 123,
'constraints' => [
]
]),
CURLOPT_HTTPHEADER => [
"API-Key: <api-key>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.hellotracks.com/api/optimizeroute"
payload := strings.NewReader("{\n \"day\": 123,\n \"account\": \"<string>\",\n \"solve\": true,\n \"index\": 123,\n \"count\": 123,\n \"constraints\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.hellotracks.com/api/optimizeroute")
.header("API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"day\": 123,\n \"account\": \"<string>\",\n \"solve\": true,\n \"index\": 123,\n \"count\": 123,\n \"constraints\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.hellotracks.com/api/optimizeroute")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"day\": 123,\n \"account\": \"<string>\",\n \"solve\": true,\n \"index\": 123,\n \"count\": 123,\n \"constraints\": {}\n}"
response = http.request(request)
puts response.read_body{
"status": 123,
"jobs": [
{}
],
"original_order": [
{}
],
"unassigned": [
{}
],
"route_updated": true,
"abort_reason": "<string>",
"route_reason": "<string>"
}Dispatch and Routing
Route Optimization
Endpoint to optimize routes
POST
/
api
/
optimizeroute
Route Optimization
curl --request POST \
--url https://api.hellotracks.com/api/optimizeroute \
--header 'API-Key: <api-key>' \
--header 'Content-Type: application/json' \
--data '
{
"day": 123,
"account": "<string>",
"solve": true,
"index": 123,
"count": 123,
"constraints": {}
}
'import requests
url = "https://api.hellotracks.com/api/optimizeroute"
payload = {
"day": 123,
"account": "<string>",
"solve": True,
"index": 123,
"count": 123,
"constraints": {}
}
headers = {
"API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
day: 123,
account: '<string>',
solve: true,
index: 123,
count: 123,
constraints: {}
})
};
fetch('https://api.hellotracks.com/api/optimizeroute', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.hellotracks.com/api/optimizeroute",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'day' => 123,
'account' => '<string>',
'solve' => true,
'index' => 123,
'count' => 123,
'constraints' => [
]
]),
CURLOPT_HTTPHEADER => [
"API-Key: <api-key>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.hellotracks.com/api/optimizeroute"
payload := strings.NewReader("{\n \"day\": 123,\n \"account\": \"<string>\",\n \"solve\": true,\n \"index\": 123,\n \"count\": 123,\n \"constraints\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.hellotracks.com/api/optimizeroute")
.header("API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"day\": 123,\n \"account\": \"<string>\",\n \"solve\": true,\n \"index\": 123,\n \"count\": 123,\n \"constraints\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.hellotracks.com/api/optimizeroute")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"day\": 123,\n \"account\": \"<string>\",\n \"solve\": true,\n \"index\": 123,\n \"count\": 123,\n \"constraints\": {}\n}"
response = http.request(request)
puts response.read_body{
"status": 123,
"jobs": [
{}
],
"original_order": [
{}
],
"unassigned": [
{}
],
"route_updated": true,
"abort_reason": "<string>",
"route_reason": "<string>"
}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:
/distributejobsand/autoassignendpoints.
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)
}
}
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.Starting index for partial route optimization. Use with
count to optimize only a subset of jobs in the route.Constraint configuration for route solving (only applies when
solve: true):working_hours(boolean, default: true): Respect worker’s working hourstime_window(boolean, default: true): Honor job time windowsskills(boolean, default: true): Match required skills with worker capabilitiescapacity(boolean, default: true): Consider pickup/dropoff capacity limitsmax_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),
route_reason: <string> (only present if route calculation failed without an abort reason)
}
Status code.
0 indicates success, other values indicate errors (e.g., permission denied).The newly arranged jobs representing the optimized route (includes full job objects). Missing when the route could not be optimized.
Array of job IDs in their original order before optimization. Useful for implementing undo functionality.
Array of job IDs that could not be placed on the route (empty unless
solve: true drops jobs). These jobs couldn’t be included due to constraint violations (e.g., time windows, capacity, skills mismatch).Only present when route solving fails. Possible values:
no_region: No routing region available for the locationimpossible_route: Route cannot be calculated with given constraintsinternal_error: Server-side error during optimizationinput_error: <details>: Invalid input parametersrouting_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_routesetting 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