Optimal Time Slot Suggestions

Overview

The suggest endpoint helps you find optimal time slots for new jobs within your existing planned routes. This feature enables dynamic scheduling by identifying the best insertion points for unplanned work while minimizing disruption to current plans.

Perfect for appointment booking systems, field service scheduling, and dynamic route optimization scenarios.

Exactly one job may be unassigned. Suggest answers the question “where does this job go?”, so the request must contain exactly one job without initialResource. Every other job needs initialResource (and normally initialArrival) to describe the schedule you are inserting into.Leaving two or more jobs unassigned is rejected. A request with no unassigned job is rejected too — there is nothing to suggest.The one exception is a job relation: you may leave every job named by a single relation unassigned, and the solver suggests a placement for the group as a whole.

How It Works

The suggest endpoint analyzes your current route plan and evaluates all possible insertion points for new jobs. For each potential slot, it calculates:

Impact on overall route efficiency
Constraint violations (if any)
Resource utilization changes
Travel time implications

The response provides ranked suggestions with detailed scoring, allowing you to offer customers the most efficient appointment options.

API Implementation

Request Structure

{
  "resources": [...],
  "jobs": [
    {
      "name": "existing-job-1",
      "initialArrival": "2023-01-13T08:01:00",
      "initialResource": "R-2",
      "duration": 600
    },
    {
      "name": "new-job-to-schedule",
      "duration": 600
      // No initialResource: this is the one job being suggested.
      // Exactly one job in the request may look like this.
    }
  ],
  "options": {
    "maxSuggestions": 5,
    "onlyFeasibleSuggestions": true
  }
}

{
  "options": {
    "maxSuggestions": 10,           // Ranked list is truncated to this many; 0 (default) returns all
    "onlyFeasibleSuggestions": false // Include infeasible options
  }
}

Response Format

{
  "suggestions": [
    {
      "score": {
        "hardScore": 0,
        "mediumScore": 0,
        "softScore": -301,
        "feasible": true
      },
      "assignments": [
        {
          "job": "new-job-to-schedule",
          "resource": "R-1",
          "suggestedArrival": "2023-01-13T08:10:00",
          "executedAfter": "JOB-1"
        }
      ]
    }
  ]
}

Complete Example

Request
Response

{
  "resources": [
    {
      "name": "R-1",
      "shifts": [
        {
          "from": "2023-01-13T08:00:00",
          "to": "2023-01-13T18:30:00"
        }
      ]
    },
    {
      "name": "R-2",
      "shifts": [
        {
          "from": "2023-01-13T08:00:00",
          "to": "2023-01-13T18:30:00"
        }
      ]
    }
  ],
  "jobs": [
    {
      "name": "JOB-1",
      "initialArrival": "2023-01-13T08:01:00",
      "initialResource": "R-2",
      "duration": 600
    },
    {
      "name": "JOB-2 is unplanned",
      "duration": 600
    },
    {
      "name": "JOB-3",
      "initialArrival": "2023-01-13T08:20:00",
      "initialResource": "R-1",
      "duration": 600
    },
    {
      "name": "JOB-4",
      "initialArrival": "2023-01-13T08:30:00",
      "initialResource": "R-1",
      "duration": 600
    },
    {
      "name": "JOB-5",
      "initialArrival": "2023-01-13T08:35:00",
      "initialResource": "R-1",
      "duration": 600
    }
  ],
  "options": {
    "maxSuggestions": 3,
    "onlyFeasibleSuggestions": true
  }
}

{
  "score": {
    "hardScore": 0,
    "mediumScore": 0,
    "softScore": -301,
    "feasible": true
  },
  "trips": [
    {
      "visits": [
        {
          "arrival": "2023-01-13T08:00:00",
          "job": "JOB-1"
        },
        {
          "arrival": "2023-01-13T08:10:00",
          "job": "JOB-2 is unplanned"
        },
        {
          "arrival": "2023-01-13T08:20:00",
          "job": "JOB-3"
        },
        {
          "arrival": "2023-01-13T08:30:00",
          "job": "JOB-4"
        },
        {
          "arrival": "2023-01-13T08:40:00",
          "job": "JOB-5"
        }
      ],
      "resource": "R-1",
      "date": "2023-01-13",
      "departureTime": "2023-01-13T08:00:00",
      "workTime": 3000,
      "serviceTime": 3000
    }
  ],
  "suggestions": [
    {
      "score": {
        "hardScore": 0,
        "mediumScore": 0,
        "softScore": -301,
        "feasible": true
      },
      "assignments": [
        {
          "job": "JOB-2 is unplanned",
          "resource": "R-1",
          "suggestedArrival": "2023-01-13T08:10:00",
          "executedAfter": "JOB-1"
        }
      ]
    },
    {
      "score": {
        "hardScore": 0,
        "mediumScore": 0,
        "softScore": -901,
        "feasible": true
      },
      "assignments": [
        {
          "job": "JOB-2 is unplanned",
          "resource": "R-1",
          "suggestedArrival": "2023-01-13T08:00:00",
          "executedAfter": "R-12023-01-13"
        }
      ]
    },
    {
      "score": {
        "hardScore": 0,
        "mediumScore": 0,
        "softScore": -901,
        "feasible": true
      },
      "assignments": [
        {
          "job": "JOB-2 is unplanned",
          "resource": "R-1",
          "suggestedArrival": "2023-01-13T08:20:00",
          "executedAfter": "JOB-3"
        }
      ]
    }
  ],
  "status": "SOLVED"
}

Key Concepts

Planned vs Unplanned Jobs

Jobs must be explicitly marked as planned using initialResource. The single job that omits it is the one suggestions are generated for.

Planned jobs: have initialResource set, and normally initialArrival as well
The unplanned job: omits initialResource — exactly one job per request, or one whole job relation
Only that job receives suggestions

initialArrival is a sequencing hint, not a pin. The solver re-times planned jobs as early as the shift allows, so a job you sent with initialArrival: 09:00 can come back at 08:01. If a booking is already promised to a customer, express it as a hard time window on that job rather than relying on initialArrival to hold it.

Suggestion Scoring

Each suggestion includes a comprehensive score breakdown:

Score Type	Description	Impact
`hardScore`	Constraint violations that must be avoided	Must be 0 for feasible solutions
`mediumScore`	Important but flexible constraints	Lower is better
`softScore`	Optimization objectives like travel time	Lower is better
`feasible`	Overall feasibility indicator	true/false

Insertion Points

The executedAfter field indicates where the job would be inserted:

Job name: Insert after the specified job
Resource+Date format: Insert at the beginning of the resource’s route for that date

Best Practices

Send the whole day, not just the new job

Every job already booked for that resource and day belongs in jobs with initialResource set (and initialArrival for the right sequence). Suggestions are only as good as the schedule you describe — omit the existing bookings and the solver has nothing to insert around.

Leave exactly one job unassigned

The new job is the only one without initialResource. Two unassigned jobs is a rejected request, not two sets of suggestions; run one request per job you want placed.

Set appropriate limits

Use maxSuggestions to balance between offering choices and API performance. Start with 5-10 suggestions. There is no upper bound — asking for more than exist returns all of them.

Handle infeasible suggestions

When onlyFeasibleSuggestions is false, check the feasible flag and hardScore to identify problematic suggestions.

Common Use Cases

Dynamic Appointment Booking

Offer customers available time slots that minimize disruption:

{
  "jobs": [
    // Every appointment already booked that day, each with "initialResource"
    // (and "initialArrival"). Only the job below is left unassigned.
    {
      "name": "new-customer-appointment",
      "duration": 3600,
      "location": {...},
      "windows": [{
        "from": "2023-01-13T09:00:00",
        "to": "2023-01-13T17:00:00"
      }]
    }
  ],
  "options": {
    "maxSuggestions": 5,
    "onlyFeasibleSuggestions": true
  }
}

Emergency Service Integration

Find the best slot for urgent work:

{
  "jobs": [
    // Regular jobs, each with "initialResource". Only the job below is left unassigned.
    {
      "name": "emergency-repair",
      "duration": 7200,
      "priority": 100,
      "tags": [{"name": "urgent"}]
    }
  ],
  "options": {
    "maxSuggestions": 3,
    "onlyFeasibleSuggestions": false  // Show all options
  }
}

Performance Considerations

The suggest endpoint evaluates multiple insertion points, making it more computationally intensive than standard solve operations. Consider caching results for frequently requested scenarios.

Use time windows to constrain the search space
Cache suggestions for common scenarios
Consider async processing for large-scale suggestions

Solve API

Complete route optimization from scratch

Evaluate API

Score existing route plans

Job Relations

Define dependencies between jobs

Time Windows

Constrain job scheduling times

Platform

VRP API

Fill API

Optimal Time Slot Suggestions

Overview

How It Works

API Implementation

Request Structure

Response Format

Complete Example

Key Concepts

Planned vs Unplanned Jobs

Suggestion Scoring

Insertion Points

Best Practices

Common Use Cases

Dynamic Appointment Booking

Emergency Service Integration

Performance Considerations

Solve API

Evaluate API

Job Relations

Time Windows

​Overview

​How It Works

​API Implementation

​Request Structure

​Response Format

​Complete Example

​Key Concepts

​Planned vs Unplanned Jobs

​Suggestion Scoring

​Insertion Points

​Best Practices

​Common Use Cases

​Dynamic Appointment Booking

​Emergency Service Integration

​Performance Considerations

​Related Features

Solve API

Evaluate API

Job Relations

Time Windows

Overview

How It Works

API Implementation

Request Structure

Response Format

Complete Example

Key Concepts

Planned vs Unplanned Jobs

Suggestion Scoring

Insertion Points

Best Practices

Common Use Cases

Dynamic Appointment Booking

Emergency Service Integration

Performance Considerations

Related Features