​
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

{
  "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
  }
}

​
Response Format

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

​
Complete Example

{
  "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
  }
}

​
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 TypeDescriptionImpact
hardScoreConstraint violations that must be avoidedMust be 0 for feasible solutions
mediumScoreImportant but flexible constraintsLower is better
softScoreOptimization objectives like travel timeLower is better
feasibleOverall feasibility indicatortrue/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

1

Define existing routes accurately

Ensure all currently planned jobs have correct initialResource and initialArrival values to represent your actual schedule.

2

Set appropriate limits

Use maxSuggest to balance between offering choices and API performance. Start with 5-10 suggestions.

3

Handle infeasible suggestions

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

4

Consider time granularity

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:

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

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

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