Actions

Suggest VRP

Returns the ranked insertion options for a single unassigned job.

Exactly one job in jobs may be left unassigned - that is the job being suggested. Every other job must carry initialResource (and normally initialArrival) to describe the schedule the new job is inserted into. Alternatively, one whole job relation may be unassigned, in which case every job named by that relation is left without initialResource. Any other combination is rejected.

Note that initialArrival is a sequencing hint, not a pin: the solver re-times already assigned jobs as early as the shift allows. Use windows on a job to hold a committed time.

POST

vrp

suggest

Suggest

curl --request POST \
  --url https://api.solvice.io/v2/vrp/suggest \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "jobs": [
    {
      "name": "1",
      "duration": 3600,
      "initialResource": "1",
      "initialArrival": "2023-01-13T09:00:00"
    },
    {
      "name": "2",
      "duration": 3600
    }
  ],
  "resources": [
    {
      "name": "1",
      "shifts": [
        {
          "from": "2023-01-13T08:00:00",
          "to": "2023-01-13T17:00:00"
        }
      ]
    }
  ]
}
'

import requests

url = "https://api.solvice.io/v2/vrp/suggest"

payload = {
    "jobs": [
        {
            "name": "1",
            "duration": 3600,
            "initialResource": "1",
            "initialArrival": "2023-01-13T09:00:00"
        },
        {
            "name": "2",
            "duration": 3600
        }
    ],
    "resources": [
        {
            "name": "1",
            "shifts": [
                {
                    "from": "2023-01-13T08:00:00",
                    "to": "2023-01-13T17:00:00"
                }
            ]
        }
    ]
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    jobs: [
      {
        name: '1',
        duration: 3600,
        initialResource: '1',
        initialArrival: '2023-01-13T09:00:00'
      },
      {name: '2', duration: 3600}
    ],
    resources: [
      {name: '1', shifts: [{from: '2023-01-13T08:00:00', to: '2023-01-13T17:00:00'}]}
    ]
  })
};

fetch('https://api.solvice.io/v2/vrp/suggest', 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.solvice.io/v2/vrp/suggest",
  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([
    'jobs' => [
        [
                'name' => '1',
                'duration' => 3600,
                'initialResource' => '1',
                'initialArrival' => '2023-01-13T09:00:00'
        ],
        [
                'name' => '2',
                'duration' => 3600
        ]
    ],
    'resources' => [
        [
                'name' => '1',
                'shifts' => [
                                [
                                                                'from' => '2023-01-13T08:00:00',
                                                                'to' => '2023-01-13T17:00:00'
                                ]
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <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.solvice.io/v2/vrp/suggest"

	payload := strings.NewReader("{\n  \"jobs\": [\n    {\n      \"name\": \"1\",\n      \"duration\": 3600,\n      \"initialResource\": \"1\",\n      \"initialArrival\": \"2023-01-13T09:00:00\"\n    },\n    {\n      \"name\": \"2\",\n      \"duration\": 3600\n    }\n  ],\n  \"resources\": [\n    {\n      \"name\": \"1\",\n      \"shifts\": [\n        {\n          \"from\": \"2023-01-13T08:00:00\",\n          \"to\": \"2023-01-13T17:00:00\"\n        }\n      ]\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<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.solvice.io/v2/vrp/suggest")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"jobs\": [\n    {\n      \"name\": \"1\",\n      \"duration\": 3600,\n      \"initialResource\": \"1\",\n      \"initialArrival\": \"2023-01-13T09:00:00\"\n    },\n    {\n      \"name\": \"2\",\n      \"duration\": 3600\n    }\n  ],\n  \"resources\": [\n    {\n      \"name\": \"1\",\n      \"shifts\": [\n        {\n          \"from\": \"2023-01-13T08:00:00\",\n          \"to\": \"2023-01-13T17:00:00\"\n        }\n      ]\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.solvice.io/v2/vrp/suggest")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"jobs\": [\n    {\n      \"name\": \"1\",\n      \"duration\": 3600,\n      \"initialResource\": \"1\",\n      \"initialArrival\": \"2023-01-13T09:00:00\"\n    },\n    {\n      \"name\": \"2\",\n      \"duration\": 3600\n    }\n  ],\n  \"resources\": [\n    {\n      \"name\": \"1\",\n      \"shifts\": [\n        {\n          \"from\": \"2023-01-13T08:00:00\",\n          \"to\": \"2023-01-13T17:00:00\"\n        }\n      ]\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "status": "SOLVING",
  "solveDuration": 123,
  "errors": [
    {
      "code": 123,
      "message": "<string>"
    }
  ],
  "warnings": [
    {
      "code": 123,
      "message": "<string>"
    }
  ]
}

{
  "message": "<string>",
  "status": "OK"
}

{
  "message": "<string>",
  "status": "OK"
}

{
  "message": "<string>",
  "status": "OK"
}

Authorizations

Authorization

string

header

required

Api Key based authentication (apikey)

Query Parameters

millis

string | null

required

Body

application/json

OnRoute Request for solving, evaluating

resources

object[]

required

List of available resources (vehicles, drivers, workers) that can be assigned to perform jobs. Each resource defines their working schedules, location constraints, capacity limits, and capabilities. At least one resource is required, with a maximum of 2000 resources per request.

Required array length: 1 - 2000 elements

Show child attributes

jobs

object[]

required

List of jobs/tasks to be assigned to resources. Each job specifies service requirements, location, time constraints, duration, and resource preferences. Jobs represent the work that needs to be scheduled and optimized. At least one job is required, with a maximum of 10,000 jobs per request.

Required array length: 1 - 10000 elements

Show child attributes

options

object

Options to tweak the routing engine

Show child attributes

Example:

{
  "euclidian": false,
  "routingEngine": "OSM",
  "partialPlanning": true,
  "minimizeResources": true,
  "traffic": 1.1,
  "polylines": true,
  "fairWorkloadPerTrip": false,
  "fairWorkloadPerResource": false,
  "workloadSensitivity": 0.1,
  "snapUnit": 300,
  "maxSuggestions": 3,
  "onlyFeasibleSuggestions": true,
  "explanation": {
    "enabled": true,
    "filterHardConstraints": true
  }
}

weights

object

OnRoute Weights

Show child attributes

Example:

{
  "priorityWeight": 100,
  "workloadSpreadWeight": 10,
  "travelTimeWeight": 1,
  "plannedWeight": 1000,
  "asapWeight": 5,
  "minimizeResourcesWeight": 3600,
  "allowedResourcesWeight": 500,
  "waitTimeWeight": 1,
  "urgencyWeight": 50,
  "driveTimeWeight": 1,
  "clusteringWeight": 1
}

costs

object

Cost configuration for financial-based optimization. When provided, the solver derives internal weights from these cost values, allowing optimization decisions to be expressed in monetary terms. All costs are in EUR (or your preferred currency - treated as unitless by the solver).

Show child attributes

Example:

{
  "drivingCostPerHour": 25,
  "waitingCostPerHour": 15,
  "distanceCostPerKm": 0.35,
  "priorityCostPerPointPerHour": 5
}

hook

string<uri> | null

Optional webhook URL that will receive a POST request with the job ID when the optimization is complete. This enables asynchronous processing where you can submit a request and be notified when results are ready, rather than waiting for the synchronous response.

customDistanceMatrices

object

Custom distance matrix configuration for multi-profile and multi-slice scenarios

Show child attributes

Example:

{
  "profileMatrices": {
    "CAR": {
      "6": "matrix-car-morning-123",
      "9": "matrix-car-midday-456",
      "16": "matrix-car-evening-789"
    },
    "TRUCK": {
      "6": "matrix-truck-morning-abc",
      "9": "matrix-truck-midday-def"
    }
  },
  "matrixServiceUrl": "https://custom-matrix-service.com/api"
}

depots

object[] | null

Optional list of depots or disposal sites. Each depot defines location, opening hours, cost, duration, and capacity. Depot names must be unique.

Show child attributes

label

string | null

Maximum string length: 255

Pattern: ^(?!.*\$\{).*$

metadata

object | null

Show child attributes

relations

object[] | null

Show child attributes

Response

Status

Status of a solve job

string

required

Job ID

status

enum<string> | null

Status of the solve.

Available options:

QUEUED,

SOLVING,

SOLVED,

ERROR

Example:

"SOLVING"

solveDuration

integer<int32> | null

Duration of the solve in seconds

errors

object[] | null

List of errors

Show child attributes

warnings

object[] | null

List of warnings

Show child attributes

Suggest

curl --request POST \
  --url https://api.solvice.io/v2/vrp/suggest \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "jobs": [
    {
      "name": "1",
      "duration": 3600,
      "initialResource": "1",
      "initialArrival": "2023-01-13T09:00:00"
    },
    {
      "name": "2",
      "duration": 3600
    }
  ],
  "resources": [
    {
      "name": "1",
      "shifts": [
        {
          "from": "2023-01-13T08:00:00",
          "to": "2023-01-13T17:00:00"
        }
      ]
    }
  ]
}
'

import requests

url = "https://api.solvice.io/v2/vrp/suggest"

payload = {
    "jobs": [
        {
            "name": "1",
            "duration": 3600,
            "initialResource": "1",
            "initialArrival": "2023-01-13T09:00:00"
        },
        {
            "name": "2",
            "duration": 3600
        }
    ],
    "resources": [
        {
            "name": "1",
            "shifts": [
                {
                    "from": "2023-01-13T08:00:00",
                    "to": "2023-01-13T17:00:00"
                }
            ]
        }
    ]
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    jobs: [
      {
        name: '1',
        duration: 3600,
        initialResource: '1',
        initialArrival: '2023-01-13T09:00:00'
      },
      {name: '2', duration: 3600}
    ],
    resources: [
      {name: '1', shifts: [{from: '2023-01-13T08:00:00', to: '2023-01-13T17:00:00'}]}
    ]
  })
};

fetch('https://api.solvice.io/v2/vrp/suggest', 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.solvice.io/v2/vrp/suggest",
  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([
    'jobs' => [
        [
                'name' => '1',
                'duration' => 3600,
                'initialResource' => '1',
                'initialArrival' => '2023-01-13T09:00:00'
        ],
        [
                'name' => '2',
                'duration' => 3600
        ]
    ],
    'resources' => [
        [
                'name' => '1',
                'shifts' => [
                                [
                                                                'from' => '2023-01-13T08:00:00',
                                                                'to' => '2023-01-13T17:00:00'
                                ]
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <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.solvice.io/v2/vrp/suggest"

	payload := strings.NewReader("{\n  \"jobs\": [\n    {\n      \"name\": \"1\",\n      \"duration\": 3600,\n      \"initialResource\": \"1\",\n      \"initialArrival\": \"2023-01-13T09:00:00\"\n    },\n    {\n      \"name\": \"2\",\n      \"duration\": 3600\n    }\n  ],\n  \"resources\": [\n    {\n      \"name\": \"1\",\n      \"shifts\": [\n        {\n          \"from\": \"2023-01-13T08:00:00\",\n          \"to\": \"2023-01-13T17:00:00\"\n        }\n      ]\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<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.solvice.io/v2/vrp/suggest")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"jobs\": [\n    {\n      \"name\": \"1\",\n      \"duration\": 3600,\n      \"initialResource\": \"1\",\n      \"initialArrival\": \"2023-01-13T09:00:00\"\n    },\n    {\n      \"name\": \"2\",\n      \"duration\": 3600\n    }\n  ],\n  \"resources\": [\n    {\n      \"name\": \"1\",\n      \"shifts\": [\n        {\n          \"from\": \"2023-01-13T08:00:00\",\n          \"to\": \"2023-01-13T17:00:00\"\n        }\n      ]\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.solvice.io/v2/vrp/suggest")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"jobs\": [\n    {\n      \"name\": \"1\",\n      \"duration\": 3600,\n      \"initialResource\": \"1\",\n      \"initialArrival\": \"2023-01-13T09:00:00\"\n    },\n    {\n      \"name\": \"2\",\n      \"duration\": 3600\n    }\n  ],\n  \"resources\": [\n    {\n      \"name\": \"1\",\n      \"shifts\": [\n        {\n          \"from\": \"2023-01-13T08:00:00\",\n          \"to\": \"2023-01-13T17:00:00\"\n        }\n      ]\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "status": "SOLVING",
  "solveDuration": 123,
  "errors": [
    {
      "code": 123,
      "message": "<string>"
    }
  ],
  "warnings": [
    {
      "code": 123,
      "message": "<string>"
    }
  ]
}

{
  "message": "<string>",
  "status": "OK"
}

{
  "message": "<string>",
  "status": "OK"
}

{
  "message": "<string>",
  "status": "OK"
}

VRP API

Fill API

Suggest VRP

Authorizations

Query Parameters

Body

Response