{
  "options": {
    "weights": {
      "travelTimeWeight": 1,
      "waitTimeWeight": 10,
      "urgencyWeight": 100,
      "priorityWeight": 50,
      "workloadSpreadWeight": 20,
      "minimizeResourcesWeight": 3600,
      "rankingWeight": 25
    }
  }
}

{
  "score": {
    "hardScore": 0,
    "mediumScore": -500,
    "softScore": -12450,
    "feasible": true
  }
}

Scoring & Explanation System

The VRP solver uses a sophisticated three-level scoring system to evaluate and optimize solutions. This guide explains how scoring works, how to interpret results, and how to use the explanation system to understand and improve your solutions.

Three-Level Scoring System

The solver evaluates solutions using three distinct score levels:

┌─────────────────────┐
│   HARD SCORE = 0   │ ← Must be 0 for feasible solution
├─────────────────────┤
│  MEDIUM SCORE ≥ 0  │ ← Minimized after hard constraints
├─────────────────────┤
│   SOFT SCORE ≥ 0   │ ← Optimized for solution quality
└─────────────────────┘

Score levels hierarchy: Hard constraints must be satisfied, then medium, then soft

Score Components

score

object

The score object in the response contains:

Show Score properties

hardScore

long

required

Must be 0 for a feasible solution. Negative values indicate constraint violations that make the solution invalid.

mediumScore

long

Secondary constraints. Should be minimized but don’t affect feasibility.

softScore

long

Quality optimizations. Higher (less negative) values indicate better solutions.

feasible

boolean

required

Quick check if hardScore = 0. True means all hard constraints are satisfied.

{
  "score": {
    "hardScore": 0,
    "mediumScore": -500,
    "softScore": -12450,
    "feasible": true
  }
}

Understanding Constraint Levels

Hard Constraints (Must Satisfy)

Hard constraints represent inviolable business rules:

{
  "windows": [{
    "from": "2024-03-15T09:00:00Z",
    "to": "2024-03-15T17:00:00Z",
    "hard": true
  }]
}

Arriving outside this window makes the solution infeasible.

{
  "windows": [{
    "from": "2024-03-15T09:00:00Z",
    "to": "2024-03-15T17:00:00Z",
    "hard": true
  }]
}

Arriving outside this window makes the solution infeasible.

{
  "resource": {
    "capacity": [1000]
  },
  "job": {
    "load": [1200]  // Exceeds capacity
  }
}

Overloading vehicles violates hard constraints.

{
  "job": {
    "tags": [{"name": "electrical", "hard": true}]
  },
  "resource": {
    "tags": ["plumbing"]  // Missing required skill
  }
}

Missing required skills makes assignment impossible.

Medium Constraints (Important)

Medium constraints are strongly preferred but can be violated:

Overtime limits (when not strict)
Preferred time windows
Some job relations

Soft Constraints (Optimize)

Soft constraints improve solution quality:

Minimize travel time
Minimize wait time
Balance workload
Customer preferences

Weight Configuration

Control the importance of different objectives using weights:

{
  "options": {
    "weights": {
      "travelTimeWeight": 1,
      "waitTimeWeight": 10,
      "urgencyWeight": 100,
      "priorityWeight": 50,
      "workloadSpreadWeight": 20,
      "minimizeResourcesWeight": 3600,
      "rankingWeight": 25
    }
  }
}

Weight Parameters

travelTimeWeight

integer

default:"1"

Base weight for travel time. Other weights are relative to this.

waitTimeWeight

integer

default:"0"

Penalty for idle time at locations. Set >0 to minimize waiting.

urgencyWeight

integer

default:"0"

Importance of scheduling urgent jobs early. Higher = more urgent jobs first.

priorityWeight

integer

default:"1"

Ensures high-priority jobs are included when capacity is limited.

workloadSpreadWeight

integer

default:"1"

Balances work across resources. Higher = more equal distribution.

minimizeResourcesWeight

integer

default:"1"

Cost of using additional vehicles. Set to hourly cost equivalent (e.g., 3600 = 1 hour travel time).

Weight Tuning Strategy:

Start with default weights
Identify which objectives aren’t meeting expectations
Increase weights for underperforming objectives
Test with 2-5x increases to see impact
Fine-tune based on results

Explanation API

Get detailed insights into constraint violations and alternative assignments:

Request Explanation

curl -X GET 'https://api.solvice.io/v2/vrp/jobs/{job_id}/explanation' \
  -H 'Authorization: YOUR_API_KEY'

Analyze Results

The explanation response includes:

Constraint violations
Score breakdown
Alternative assignments
Unassigned job reasons

Explanation Response Structure

{
  "score": {
    "hardScore": -1000,
    "mediumScore": 0,
    "softScore": -15230,
    "feasible": false
  },
  "conflicts": [
    {
      "constraint": "TIME_WINDOW_CONFLICT",
      "score": "-1000",
      "job": "delivery-5",
      "resource": "van-1"
    }
  ],
  "unresolved": [
    {
      "constraint": "TRAVEL_TIME",
      "score": "-15230"
    }
  ],
  "alternatives": {
    "delivery-5": [
      {
        "job": "delivery-5",
        "resource": "van-2",
        "suggestedArrival": "2024-03-15T14:30:00Z",
        "executedAfter": "delivery-3",
        "score": {
          "hardScore": 0,
          "softScore": -16450,
          "feasible": true
        }
      }
    ]
  }
}

Constraint Types Reference

Hard Constraints

Constraint	Description	Common Cause
`TIME_WINDOW_CONFLICT`	Job scheduled outside time window	Tight schedules, too many jobs
`TRIP_CAPACITY`	Vehicle capacity exceeded	Underestimated loads, few vehicles
`TAG_HARD`	Missing required skill/tag	Skill mismatch
`SHIFT_END_CONFLICT`	Work extends past shift end	Long routes, late starts
`MAX_DRIVE_TIME`	Legal driving limit exceeded	Long distances
`DISALLOWED_RESOURCES`	Job assigned to blacklisted resource	Configuration error

Medium Constraints

Constraint	Description	Impact
`OVERTIME_END_CONFLICT`	Work extends into overtime	Additional costs
`DATE_TIME_WINDOW_CONFLICT_SOFT`	Soft time window violated	Customer dissatisfaction
`SAME_TRIP`	Related jobs on different trips	Inefficiency

Soft Constraints

Constraint	Description	Optimization Goal
`TRAVEL_TIME`	Total travel time	Minimize
`WAIT_TIME`	Idle time at locations	Minimize
`RESOURCE_ACTIVATION`	Number of vehicles used	Minimize
`RANKING_SOFT`	Resource preference score	Match preferences
`FAIR_WORK`	Workload imbalance	Equalize

Unassigned Jobs Analysis

When jobs can’t be assigned, the response includes detailed reasons:

{
  "unserved": ["job-15", "job-23"],
  "unservedReasons": {
    "job-15": [
      "TIME_WINDOW_CONFLICT",
      "TRIP_CAPACITY"
    ],
    "job-23": [
      "TAG_HARD",
      "SHIFT_END_CONFLICT"
    ]
  }
}

Common Unassigned Reasons

TIME_WINDOW_CONFLICT

TRIP_CAPACITY

TAG_HARD

SHIFT_END_CONFLICT

Alternative Assignments

The explanation API can suggest alternative assignments:

{
  "options": {
    "explanation": {
      "enabled": true,
      "filterHardConstraints": true,
      "onlyUnassigned": false
    }
  }
}

Understanding Alternatives

Each alternative shows:

Resource: Which vehicle could take the job
Position: Where in the route (after which job)
Timing: Suggested arrival time
Score Impact: How it affects the overall score

Alternatives are particularly useful for:

Manual adjustments
Understanding trade-offs
Identifying bottlenecks
Customer negotiations

Improving Solutions

Strategy 1: Fix Infeasibilities First

Identify Hard Violations

Check the conflicts array for hard constraints

Address Root Causes

Add resources
Adjust time windows
Modify capacity
Update skills

Re-solve

Submit updated request

Strategy 2: Optimize Quality

Once feasible, improve soft score:

{
  "weights": {
    "travelTimeWeight": 5  // Increase from 1
  }
}

{
  "weights": {
    "travelTimeWeight": 5  // Increase from 1
  }
}

{
  "weights": {
    "workloadSpreadWeight": 50  // Increase significantly
  }
}

{
  "weights": {
    "minimizeResourcesWeight": 7200  // 2-hour penalty
  }
}

Strategy 3: Use Partial Planning

When full assignment is impossible:

{
  "options": {
    "partialPlanning": true
  }
}

With partial planning, focus on:

High-priority jobs getting assigned
Understanding why others failed
Planning follow-up solutions

Best Practices

Score Interpretation Guidelines:

Feasibility First: Always achieve hardScore = 0 before optimizing
Baseline Comparison: Save scores from good solutions as benchmarks
Incremental Changes: Adjust one weight at a time to understand impact
Document Weights: Record why specific weights were chosen
Monitor Trends: Track how scores change with different inputs

Performance Considerations

The explanation API adds computational overhead:

{
  "options": {
    "explanation": {
      "enabled": false
    }
  }
}

Use for production routing

{
  "options": {
    "explanation": {
      "enabled": false
    }
  }
}

Use for production routing

{
  "options": {
    "explanation": {
      "enabled": true,
      "filterHardConstraints": true
    }
  }
}

Use for analysis and debugging

Constraint Configuration

Deep dive into specific constraints

Solution Quality

Metrics for evaluating solutions

Unassigned Reasons

Debug unassigned jobs

Advanced Constraints

Complex constraint configuration

VRP Constraint SystemUnderstanding how constraints shape and optimize your routing solutions

{
  "options": {
    "weights": {
      "travelTimeWeight": 1,
      "waitTimeWeight": 10,
      "urgencyWeight": 100,
      "priorityWeight": 50,
      "workloadSpreadWeight": 20,
      "minimizeResourcesWeight": 3600,
      "rankingWeight": 25
    }
  }
}

{
  "score": {
    "hardScore": 0,
    "mediumScore": -500,
    "softScore": -12450,
    "feasible": true
  }
}

Platform

VRP API

Scoring & Explanation System

Scoring & Explanation System

Three-Level Scoring System

Score Components

Understanding Constraint Levels

Hard Constraints (Must Satisfy)

Medium Constraints (Important)

Soft Constraints (Optimize)

Weight Configuration

Weight Parameters

Explanation API

Explanation Response Structure

Constraint Types Reference

Hard Constraints

Medium Constraints

Soft Constraints

Unassigned Jobs Analysis

Common Unassigned Reasons

Alternative Assignments

Understanding Alternatives

Improving Solutions

Strategy 1: Fix Infeasibilities First

Strategy 2: Optimize Quality

Strategy 3: Use Partial Planning

Best Practices

Performance Considerations

Constraint Configuration

Solution Quality

Unassigned Reasons

Advanced Constraints

Platform

VRP API

​Scoring & Explanation System

​Three-Level Scoring System

​Score Components

​Understanding Constraint Levels

​Hard Constraints (Must Satisfy)

​Medium Constraints (Important)

​Soft Constraints (Optimize)

​Weight Configuration

​Weight Parameters

​Explanation API

​Explanation Response Structure

​Constraint Types Reference

​Hard Constraints

​Medium Constraints

​Soft Constraints

​Unassigned Jobs Analysis

​Common Unassigned Reasons

​Alternative Assignments

​Understanding Alternatives

​Improving Solutions

​Strategy 1: Fix Infeasibilities First

​Strategy 2: Optimize Quality

​Strategy 3: Use Partial Planning

​Best Practices

​Performance Considerations

​Related Topics

Constraint Configuration

Solution Quality

Unassigned Reasons

Advanced Constraints

Scoring & Explanation System

Three-Level Scoring System

Score Components

Understanding Constraint Levels

Hard Constraints (Must Satisfy)

Medium Constraints (Important)

Soft Constraints (Optimize)

Weight Configuration

Weight Parameters

Explanation API

Explanation Response Structure

Constraint Types Reference

Hard Constraints

Medium Constraints

Soft Constraints

Unassigned Jobs Analysis

Common Unassigned Reasons

Alternative Assignments

Understanding Alternatives

Improving Solutions

Strategy 1: Fix Infeasibilities First

Strategy 2: Optimize Quality

Strategy 3: Use Partial Planning

Best Practices

Performance Considerations

Related Topics