> ## Documentation Index
> Fetch the complete documentation index at: https://docs.solvice.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Optimal Time Slot Suggestions
> Find the best available time slots for new jobs in existing routes
## 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.
## 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
```json Basic Request theme={null}
{
"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 or initialArrival
}
],
"options": {
"maxSuggest": 5,
"onlyFeasibleSuggestions": true
}
}
```
```json Advanced Options theme={null}
{
"options": {
"maxSuggest": 10, // Maximum suggestions to return
"onlyFeasibleSuggestions": false, // Include infeasible options
"suggestionTimeGranularity": 300 // 5-minute intervals
}
}
```
### Response Format
```json theme={null}
{
"suggestions": [
{
"score": {
"hardScore": 0,
"mediumScore": 0,
"softScore": -301,
"feasible": true
},
"resource": "R-1",
"date": "2023-01-13T08:10:00",
"executedAfter": "JOB-1"
}
]
}
```
## Complete Example
```json theme={null}
{
"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": {
"maxSuggest": 3,
"onlyFeasibleSuggestions": true
}
}
```
```json theme={null}
{
"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
},
"resource": "R-1",
"date": "2023-01-13T08:10:00",
"executedAfter": "JOB-1"
},
{
"score": {
"hardScore": 0,
"mediumScore": 0,
"softScore": -901,
"feasible": true
},
"resource": "R-1",
"date": "2023-01-13T08:00:00",
"executedAfter": "R-12023-01-13"
},
{
"score": {
"hardScore": 0,
"mediumScore": 0,
"softScore": -901,
"feasible": true
},
"resource": "R-1",
"date": "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` and `initialArrival`. Jobs without these fields are considered candidates for suggestion.
* **Planned jobs**: Have both `initialResource` and `initialArrival` set
* **Unplanned jobs**: Missing one or both initialization fields
* Only unplanned jobs receive suggestions
### 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
Ensure all currently planned jobs have correct `initialResource` and `initialArrival` values to represent your actual schedule.
Use `maxSuggest` to balance between offering choices and API performance. Start with 5-10 suggestions.
When `onlyFeasibleSuggestions` is false, check the `feasible` flag and `hardScore` to identify problematic suggestions.
For appointment booking, set `suggestionTimeGranularity` to match your booking intervals (e.g., 900 for 15-minute slots).
## Common Use Cases
### Dynamic Appointment Booking
Offer customers available time slots that minimize disruption:
```json theme={null}
{
"jobs": [
// Existing appointments...
{
"name": "new-customer-appointment",
"duration": 3600,
"location": {...},
"windows": [{
"from": "2023-01-13T09:00:00",
"to": "2023-01-13T17:00:00"
}]
}
],
"options": {
"maxSuggest": 5,
"onlyFeasibleSuggestions": true,
"suggestionTimeGranularity": 1800 // 30-minute slots
}
}
```
### Emergency Service Integration
Find the best slot for urgent work:
```json theme={null}
{
"jobs": [
// Regular jobs...
{
"name": "emergency-repair",
"duration": 7200,
"priority": 100,
"tags": [{"name": "urgent"}]
}
],
"options": {
"maxSuggest": 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.
* Limit the number of unplanned jobs per request
* Use time windows to constrain the search space
* Cache suggestions for common scenarios
* Consider async processing for large-scale suggestions
## Related Features
Complete route optimization from scratch
Score existing route plans
Define dependencies between jobs
Constrain job scheduling times