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
API Implementation
Request Structure
Response Format
Complete Example
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
andinitialArrival
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
TheexecutedAfter
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:Emergency Service Integration
Find the best slot for urgent work: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