POST
/
v2
/
vrp
/
sync
/
suggest
Synchronous Suggest
curl --request POST \
  --url https://api.solvice.io/v2/vrp/sync/suggest \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "jobs": [
    {
      "name": "1",
      "duration": 3600
    },
    {
      "name": "2",
      "duration": 3600
    }
  ],
  "resources": [
    {
      "name": "1"
    }
  ]
}'
{
  "id": "0000-00000-00000-0000",
  "status": "SOLVED",
  "score": {
    "hard": 0,
    "soft": -12345,
    "feasible": true
  },
  "trips": [
    {
      "resource": "vehicle-1",
      "date": "2023-01-13T00:00:00Z",
      "departureTime": "2023-01-13T08:00:00Z",
      "visits": [
        {
          "job": "Job-1",
          "arrival": "2023-01-13T08:30:00Z",
          "serviceTime": 600,
          "travelTime": 1800,
          "distance": 15000,
          "location": {
            "latitude": 51.0543,
            "longitude": 3.7174
          },
          "waitTime": 0
        }
      ],
      "waitTime": 0,
      "travelTime": 3600,
      "distance": 30000,
      "workTime": 4200,
      "serviceTime": 600,
      "occupancy": 0.47
    }
  ],
  "totalWaitTimeInSeconds": 0,
  "totalTravelTimeInSeconds": 3600,
  "totalTravelDistanceInMeters": 30000,
  "totalServiceTimeInSeconds": 600,
  "occupancy": 0.47,
  "workloadFairness": 0.95,
  "unserved": [],
  "suggestions": [],
  "messages": [
    "Solution found in 2.5 seconds"
  ]
}

Authorizations

​
Authorization
string
header
required

Api Key based authentication (apikey)

Query Parameters

​
millis
string | null

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
​
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
​
options
object

Configuration options that control the solver's behavior, optimization strategy, and output format. These settings affect how the solver approaches the problem, what data is included in responses, and performance characteristics. Options to tweak the routing engine

Examples:
{
  "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

Relative importance weights for different optimization objectives and constraint violations. These weights allow you to balance competing priorities such as travel time vs. resource utilization, or to emphasize certain constraints like customer preferences or service urgency. OnRoute Weights

Examples:
{
  "priorityWeight": 100,
  "workloadSpreadWeight": 10,
  "travelTimeWeight": 1,
  "plannedWeight": 1000,
  "asapWeight": 5,
  "minimizeResourcesWeight": 3600,
  "allowedResourcesWeight": 500,
  "waitTimeWeight": 1,
  "urgencyWeight": 50,
  "driveTimeWeight": 1
}
​
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

Optional configuration for custom distance matrices supporting multiple vehicle profiles and time slices. When provided, these matrix IDs will be used instead of calculating distances through routing engines. This is useful for scenarios requiring pre-computed distance matrices with specific routing constraints or for improved performance. Custom distance matrix configuration for multi-profile and multi-slice scenarios

Examples:
{
  "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"
}
​
label
string | null
​
relations
object[] | null

Response

Suggestions

OnRoute response from solve

​
trips
object[]
required

Actual solution: trips per shift/day and per resource

​
id
string | null

Id of the solve job

Examples:

"0000-00000-00000-0000"

​
status
enum<string> | null

Status of the Response Status of the solve job.

Available options:
ERROR,
QUEUED,
SOLVING,
SOLVED
Examples:

"SOLVED"

​
score
object | null

Score tells you how good a solution is. The score of a solution shows how good this solution is w.r.t all the constraints. All solvers try to maximize the score.

​
unresolved
any

Constraints that are violated

​
totalWaitTimeInSeconds
integer | null

Wait time for all resources

Examples:

123

​
occupancy
number | null

How full this schedule is in terms of work time (incl travel) over capacity. Eg 80%

Examples:

0.8

​
totalTravelDistanceInMeters
integer | null

Travel distance for all resources in meters

Examples:

123

​
totalTravelTimeInSeconds
integer | null

Travel time for all resources

Examples:

123

​
totalServiceTimeInSeconds
integer | null

Service time for all resources

Examples:

123

​
unserved
string[] | null

Unserved jobs

Examples:

"[job-1]"

​
unservedReasons
object | null

Reasons why jobs could not be served, mapped by job name

Examples:
{
  "job-1": [
    "DATE_TIME_WINDOW_CONFLICT",
    "TRIP_CAPACITY"
  ]
}
​
suggestions
object[] | null

List of suggested assignments returned by suggest api call

​
messages
string[] | null

Events and warnings generated during the solver execution

​
violations
object[] | null
​
workloadFairness
number | null