> ## 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. # Solve VRP > Will trigger the solver run asynchronously. ## OpenAPI ````yaml vrp POST /v2/vrp/solve openapi: 3.1.0 info: description: |2- Welcome to the Solvice API! You can use our API to access Solvice API endpoints, which can get information on your solved jobs, their statuses and of course post new solve jobs. title: VRP API version: '2.0' servers: - url: https://api.solvice.io description: Production API security: - apikey: [] tags: - name: VRP API description: VRP API paths: /v2/vrp/solve: post: tags: - Actions summary: Solve description: Will trigger the solver run asynchronously. operationId: solveVRP parameters: - name: millis in: query schema: type: - string - 'null' - name: instance in: header schema: type: - string - 'null' requestBody: content: application/json: schema: $ref: '#/components/schemas/OnRouteRequest' required: true responses: '200': description: Status content: application/json: schema: $ref: '#/components/schemas/SolviceStatusJob' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' '427': description: Too many requests. content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' '500': description: Internal error content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' components: schemas: OnRouteRequest: type: object required: - resources - jobs examples: - jobs: - name: '1' duration: 3600 - name: '2' duration: 3600 resources: - name: '1' description: OnRoute Request for solving, evaluating properties: resources: type: array maxItems: 2000 minItems: 1 uniqueItems: true items: $ref: '#/components/schemas/Resource' description: >- List of available resources (vehicles, drivers, workers) that can be assigned to perform jobs. Each resource defines their working schedules, location constraints, capacity limits, and capabilities. At least one resource is required, with a maximum of 2000 resources per request. jobs: type: array maxItems: 10000 minItems: 1 uniqueItems: true items: $ref: '#/components/schemas/Job' description: >- List of jobs/tasks to be assigned to resources. Each job specifies service requirements, location, time constraints, duration, and resource preferences. Jobs represent the work that needs to be scheduled and optimized. At least one job is required, with a maximum of 10,000 jobs per request. options: type: object description: >- Configuration options that control the solver's behavior, optimization strategy, and output format. These settings affect how the solver approaches the problem, what data is included in responses, and performance characteristics. anyOf: - $ref: '#/components/schemas/Options' - type: 'null' weights: type: object description: >- Relative importance weights for different optimization objectives and constraint violations. These weights allow you to balance competing priorities such as travel time vs. resource utilization, or to emphasize certain constraints like customer preferences or service urgency. anyOf: - $ref: '#/components/schemas/Weights' - type: 'null' costs: type: object description: >- Financial cost configuration for cost-based optimization. When provided, the solver derives weights from these monetary values, enabling optimization in EUR/USD terms. This is an alternative to manual weight tuning - costs are more intuitive as they directly represent business costs. If both costs and weights are provided, costs take precedence. anyOf: - $ref: '#/components/schemas/CostConfiguration' - type: 'null' hook: type: - string - 'null' format: uri description: >- Optional webhook URL that will receive a POST request with the job ID when the optimization is complete. This enables asynchronous processing where you can submit a request and be notified when results are ready, rather than waiting for the synchronous response. customDistanceMatrices: type: object description: >- Optional configuration for custom distance matrices supporting multiple vehicle profiles and time slices. When provided, these matrix IDs will be used instead of calculating distances through routing engines. This is useful for scenarios requiring pre-computed distance matrices with specific routing constraints or for improved performance. anyOf: - $ref: '#/components/schemas/CustomDistanceMatrices' - type: 'null' depots: type: - array - 'null' items: $ref: '#/components/schemas/Depot' description: >- Optional list of depots or disposal sites. Each depot defines location, opening hours, cost, duration, and capacity. Depot names must be unique. label: type: - string - 'null' maxLength: 255 pattern: ^(?!.*\$\{).*$ relations: type: - array - 'null' items: $ref: '#/components/schemas/Relation' SolviceStatusJob: type: object required: - id description: Status of a solve job title: '' properties: id: type: string description: Job ID status: type: - string - 'null' enum: - QUEUED - SOLVING - SOLVED - ERROR examples: - SOLVING description: Status of the solve. solveDuration: type: - integer - 'null' format: int32 description: Duration of the solve in seconds errors: type: - array - 'null' items: $ref: '#/components/schemas/Message' description: List of errors warnings: type: - array - 'null' items: $ref: '#/components/schemas/Message' description: List of warnings ErrorMessage: type: object required: - message - status properties: message: type: string description: Message status: $ref: '#/components/schemas/Status' type: string description: HTTP status Resource: type: object required: - name - shifts examples: - name: vehicle-1 shifts: - from: '2023-01-13T08:00:00Z' to: '2023-01-13T17:00:00Z' start: latitude: 51.0543 longitude: 3.7174 end: latitude: 51.0543 longitude: 3.7174 breaks: - type: WINDOWED duration: 1800 from: '2023-01-13T12:00:00Z' to: '2023-01-13T13:00:00Z' maxDriveTimeInSeconds: 28800 maxDriveTimeJob: 7200 tags: - plumbing - electrical category: CAR region: latitude: 51.05 longitude: 3.72 rules: - type: MAX_SERVICE_TIME value: 28800 period: WEEK capacity: - 500 - 200 hourlyCost: 25 description: Resource (vehicle, employee) properties: name: type: string examples: - vehicle_1 maxLength: 255 pattern: ^(?!.*\$\{)[^<>"';`\\\x00]*$ description: >- Unique identifier for this resource. Used to reference the resource in job assignments, relations, and results. Must be unique within the request. shifts: type: - array - 'null' items: $ref: '#/components/schemas/Shift' description: >- List of work shifts defining when this resource is available for job assignments. Each shift specifies working hours, start/end locations, breaks, and other constraints. Multiple shifts allow for multi-day planning or split-shift schedules. At least one shift is required. start: type: - object - 'null' deprecated: true description: >- Default start location for all shifts of this resource. This field is deprecated in favor of specifying start locations individually for each shift in the shifts array, which provides more flexibility for multi-day planning. anyOf: - $ref: '#/components/schemas/Location' - type: 'null' end: type: - object - 'null' deprecated: true description: >- Default end location for all shifts of this resource. This field is deprecated in favor of specifying end locations individually for each shift in the shifts array, which provides more flexibility for multi-day planning. anyOf: - $ref: '#/components/schemas/Location' - type: 'null' maxDriveTimeInSeconds: description: >- Maximum total driving time allowed for this resource per shift or planning period. This constraint prevents excessive driving and ensures compliance with regulations or operational policies. Measured in seconds and includes all travel between jobs but excludes service time. maxDriveDistance: type: - integer - 'null' format: int32 description: >- Maximum total distance allowed for this resource per shift or planning period. This constraint prevents excessive driving and ensures compliance with regulations or operational policies. Measured in meters and includes all travel between jobs but excludes service time. region: type: - object - 'null' description: >- Preferred geographic region for this resource's job assignments. The solver will try to assign jobs that are geographically closer to this location, minimizing travel distance and time. This creates a soft constraint that influences job assignment without being mandatory. anyOf: - $ref: '#/components/schemas/Location' - type: 'null' tags: type: - array - 'null' items: type: string description: >- List of capability tags that define what types of jobs this resource can perform. Tags create matching constraints between jobs and resources - only resources with matching tags can be assigned to jobs that require those capabilities. For example, 'plumbing' or 'electrical' tags. category: type: - string - 'null' enum: - CAR - BIKE - TRUCK description: >- Transportation mode used by this resource, affecting routing calculations and capabilities. CAR provides standard vehicle routing, BIKE uses bicycle-friendly routes and speeds, TRUCK uses heavy vehicle routing with appropriate restrictions. This is a beta feature. anyOf: - $ref: '#/components/schemas/Category' - type: 'null' rules: type: - array - 'null' items: $ref: '#/components/schemas/Rule' description: >- List of periodic constraints that apply to this resource over specified time periods. Rules can enforce minimum/maximum work time, service time, drive time, or job complexity limits. These constraints ensure compliance with labor regulations, operational policies, or capacity limitations. capacity: type: - array - 'null' maxItems: 5 examples: - - 500 - 200 items: type: integer format: int32 description: >- Multi-dimensional capacity limits for this resource, such as weight, volume, or item count. Each dimension corresponds to job load requirements. For example, [500, 200] might represent 500 kg weight capacity and 200 cubic meters volume capacity. Maximum 5 dimensions supported. loadCompatibility: type: - array - 'null' examples: - - - 8000 - 0 - - 0 - 5000 items: type: object description: >- Load compatibility matrix that restricts which load types can coexist on the vehicle. loadCompatibility[i][j] = effective max capacity for dimension j when dimension i has non-zero load. When multiple dimensions are active, effective capacity for j = min(loadCompatibility[i][j]) over all active i. Matrix dimensions must match capacity size. When not provided, no load compatibility constraints are enforced. hourlyCost: type: - integer - 'null' format: int32 examples: - 60 description: >- Hourly cost rate for this resource in your currency units. Used to calculate total labor costs for solutions. Only counts active time (driving, servicing, or waiting), not idle time. This enables cost-based optimization and financial analysis of routing solutions. minimum: 0 compatibleResources: type: - array - 'null' examples: - - driver2 - driver3 items: type: string description: >- List of resource names that this resource is compatible to work with on linked jobs requiring cooperation maxDriveTime: type: - integer - 'null' format: int32 maxDriveTimeJob: type: - integer - 'null' format: int32 Job: type: object required: - name examples: - name: Job-1 duration: 600 location: latitude: 51.0543 longitude: 3.7174 priority: 100 urgency: 80 tags: - name: plumbing windows: - from: '2023-01-13T08:00:00Z' to: '2023-01-13T12:00:00Z' durationSquash: 30 plannedDate: '2023-01-13' plannedResource: vehicle-1 plannedArrival: '2023-01-13T09:00:00Z' hard: true hardWeight: 1 padding: 300 load: - 5 - 10 initialResource: vehicle-1 initialArrival: '2023-01-13T09:00:00Z' disallowedResources: - vehicle-3 - vehicle-4 description: A job to be performed by a resource. properties: name: type: string examples: - Job-1 maxLength: 255 pattern: ^(?!.*\$\{)[^<>"';`\\\x00]*$ description: Unique description duration: type: - integer - 'null' format: int32 examples: - 5 description: Service duration of the job minimum: 0 location: type: - object - 'null' description: Job location anyOf: - $ref: '#/components/schemas/Location' - type: 'null' priority: type: - integer - 'null' format: int32 examples: - 100 description: >- Priority level that influences job selection during optimization. Higher priority jobs are more likely to be included in the final solution when not all jobs can be assigned due to resource or time constraints. The priority is multiplied by job duration to calculate the selection weight. Particularly important when partialPlanning is enabled. Default value is 1. minimum: 0 urgency: type: - integer - 'null' format: int32 examples: - 100 description: >- Urgency level that influences the scheduling order of jobs. Higher urgency jobs are preferentially scheduled earlier in the day and earlier in the planning period, helping ensure time-critical tasks are completed first. This affects the sequence of job execution rather than job selection. minimum: 0 tags: type: - array - 'null' items: $ref: '#/components/schemas/Tag' description: >- List of skill or capability tags that define resource requirements for this job. Tags create hard or soft constraints linking jobs to resources with matching capabilities. For example, a 'plumbing' tag ensures only resources with plumbing skills can be assigned to plumbing jobs. rankings: type: - array - 'null' items: $ref: '#/components/schemas/Ranking' description: >- List of resource preference rankings for this job. Each ranking specifies a resource name and a preference score (1-100), where lower values indicate stronger preference. This allows jobs to have preferred resources while still allowing assignment to other resources if needed, with the preference reflected in the optimization score. proficiency: type: - array - 'null' items: $ref: '#/components/schemas/Proficiency' description: >- List of resource proficiency modifiers for this job. Each entry specifies how efficiently a specific resource can complete this job by adjusting the effective service duration. Resources with lower durationModifier values (e.g., 0.8) complete the job faster, while higher values (e.g., 1.5) indicate slower completion. windows: type: - array - 'null' items: $ref: '#/components/schemas/DateWindow' description: >- List of time windows during which this job can be started or executed. Each window defines a start and end time, creating temporal constraints for job scheduling. Multiple windows allow for flexible scheduling across different time periods. Jobs can only be assigned within these time boundaries. durationSquash: type: - integer - 'null' format: int32 examples: - 30 description: >- Reduced service duration when this job is performed at the same location immediately after another job. This optimization recognizes that setup time, travel within a building, or equipment preparation may be shared between consecutive jobs at the same location. For example, if duration=600 and durationSquash=30, the second job at the same location takes only 30 seconds instead of 600. plannedDate: type: - string - 'null' format: Date string examples: - '2022-03-10' description: >- Fixed date assignment for this job that must be respected during optimization. When specified, the job can only be scheduled on this specific date, creating a hard constraint that the solver must honor. Useful for jobs that are already committed to customers or have date-specific requirements. plannedResource: type: - string - 'null' maxLength: 255 pattern: ^(?!.*\$\{)[^<>"';`\\\x00]*$ description: >- Fixed resource assignment for this job that must be respected during optimization. When specified, only the named resource can be assigned to this job, creating a hard constraint. Combined with plannedArrival, this allows for pre-committed assignments that the solver must work around when optimizing other jobs. plannedArrival: type: - string - 'null' format: ISO8601 datetime string examples: - '2023-01-13T09:00:00Z' description: >- Fixed arrival time for this job that creates a soft constraint during optimization. The solver will try to schedule the job as close as possible to this time, with deviations penalized in the score according to the plannedWeight. This allows for customer appointment times or preferred scheduling while maintaining optimization flexibility. hard: type: - boolean - 'null' examples: - true description: >- In the case of partialPlanning planning, this indicates whether this order should be integrated into the planning or not. hardWeight: type: - integer - 'null' format: int32 examples: - 1 description: >- In the case of partialPlanning planning, this indicates the weight of this order. padding: type: - integer - 'null' format: int32 examples: - 300 description: Padding time before and after the job. In seconds minimum: 0 load: type: - array - 'null' examples: - - 5 - 10 items: type: integer format: int32 description: Load allowedResources: type: - array - 'null' deprecated: true items: type: string description: List of vehicle names that are allowed to be assigned to this order. initialResource: type: - string - 'null' maxLength: 255 pattern: ^(?!.*\$\{)[^<>"';`\\\x00]*$ description: >- Warm start for the assigned resource: name of the vehicle to which this job is planned. Use this to speed up the solver and to start from an initial solution. initialArrival: type: - string - 'null' format: ISO8601 datetime string examples: - 2023-01-13T09:00 description: >- Warm start for the arrival time. Use this to speed up the solver and to start from an initial solution. initialDepot: type: - string - 'null' maxLength: 255 pattern: ^(?!.*\$\{)[^<>"';`\\\x00]*$ description: >- Warm start for the depot: name of the depot that should be visited after this job. Requires depots to be defined in the request. disallowedResources: type: - array - 'null' items: type: string description: List of vehicle names that are allowed to be assigned to this order. complexity: type: - integer - 'null' format: int32 examples: - 1 description: Complexity of the job resumable: type: - boolean - 'null' description: >- Enables job interruption by resource unavailability breaks. When true, the job can start before a break, pause during the break, and resume afterward. Default: false. jobTypes: type: - array - 'null' examples: - - Initial Appointment - Wound Care items: type: string description: >- List of job types that this job represents. Used to enforce job type limitations per resource per timeframe. Options: type: object examples: - euclidian: false routingEngine: OSM partialPlanning: true minimizeResources: true traffic: 1.1 polylines: true fairWorkloadPerTrip: false fairWorkloadPerResource: false workloadSensitivity: 0.1 snapUnit: 300 maxSuggestions: 3 onlyFeasibleSuggestions: true explanation: enabled: true filterHardConstraints: true description: Options to tweak the routing engine properties: euclidian: type: - boolean - 'null' examples: - false description: >- Use euclidean distance calculations for travel time and distance instead of real road networks. When true, straight-line distances are used which is faster but less accurate. When false (default), routing engines like OSM, TomTom, or Google provide real road distances and travel times. routingEngine: type: - string - 'null' description: >- The routing engine used for calculating real-world distances and travel times. OSM (OpenStreetMaps) is free but basic, TomTom and Google provide more accurate traffic data and routing but require API keys. Only effective when euclidean is false. anyOf: - $ref: '#/components/schemas/RoutingEngine' - type: 'null' partialPlanning: type: - boolean - 'null' examples: - true description: >- Allow the solver to create solutions where not all jobs are assigned to resources. When true (default), the solver will assign as many jobs as possible while respecting constraints. When false, the solver will only accept solutions where all jobs are assigned, which may result in infeasible solutions. minimizeResources: type: - boolean - 'null' examples: - true description: >- Primary optimization objective. When true, the solver prioritizes using fewer resources (vehicles/drivers) even if it increases total travel time. When false, the solver prioritizes minimizing total travel time even if it requires more resources. This fundamentally changes the optimization strategy. traffic: type: - number - 'null' format: double examples: - 1.1 description: >- Global traffic multiplier applied to all travel times. A value of 1.1 increases travel times by 10% to account for traffic congestion. For real-time traffic data, use TomTom or Google routing engines. This is a simple approximation for scenarios where precise traffic data is unavailable. polylines: type: - boolean - 'null' examples: - true description: >- Generate detailed route polylines (encoded route geometries) for each trip segment. When true, the response includes polyline data that can be used to draw routes on maps. This increases processing time and response size but provides visual route information for mapping applications. fairWorkloadPerTrip: type: - boolean - 'null' examples: - false description: >- Enable workload balancing across all resources and all days/trips. When true, the solver attempts to distribute service time evenly across all resources and time periods, preventing overloading of specific resources or days. The effectiveness is controlled by `Weights.workloadSpreadWeight` and `options.workloadSensitivity`. fairWorkloadPerResource: type: - boolean - 'null' examples: - false description: >- Enable workload balancing across different days for each individual resource. When true, the solver ensures that each resource's workload is distributed evenly across their available days, preventing some days from being overloaded while others are underutilized. Works in conjunction with `Weights.workloadSpreadWeight` and `options.workloadSensitivity`. snapUnit: type: - integer - 'null' format: int32 examples: - 300 description: >- Time granularity in seconds for arrival time snapping. All calculated arrival times are rounded up to the nearest multiple of this value. For example, with snapUnit=300 (5 minutes), an arrival time of 08:32 becomes 08:35. This helps create more practical schedules by avoiding precise timings that are difficult to follow in real operations. The snapping affects score calculation during optimization. maxSuggestions: type: - integer - 'null' format: int32 description: >- Maximum number of alternative assignment suggestions to return when using the suggestion endpoint. The solver generates multiple assignment options for unassigned jobs, ranked by quality. A value of 0 (default) returns all possible suggestions, while values 1-5 limit the results to the best alternatives. Higher values increase response time but provide more options. maximum: 5 minimum: 0 onlyFeasibleSuggestions: type: - boolean - 'null' examples: - true description: >- Filter suggestions based on feasibility. When true (default), only suggestions that don't violate hard constraints are returned if the initial plan is feasible. If the initial plan is infeasible, only suggestions that don't worsen the infeasibility are returned. When false, all suggestions are returned regardless of feasibility, which may include constraint violations. enableClustering: type: boolean examples: - false description: >- Enable geographic clustering constraint to discourage route overlap. When enabled, routes are penalized if their bounding boxes overlap, encouraging visually distinct geographic territories for each route. This is a soft constraint that promotes clearer route separation without strictly enforcing non-overlapping regions. Default: false. clusteringThresholdMeters: type: integer format: int32 examples: - 10000 description: >- Clustering threshold in meters defining the buffer zone around each route's bounding box. Routes whose expanded bounding boxes (including buffer) overlap will be penalized based on their actual overlap area. This threshold acts as a proximity trigger - routes should ideally stay at least this distance apart. Default: 10000 meters (10km). jobProximityRadius: type: - integer - 'null' format: int32 examples: - 5000 description: >- Proximity radius in meters for grouping jobs as neighbors. Jobs within this distance of each other are considered neighbors for proximity-based constraints and optimizations. When set, the solver can leverage geographic proximity patterns to optimize routing decisions. jobProximityDistanceType: type: - string - 'null' description: >- Distance calculation method for job proximity determination. REAL uses actual road network distances from the routing engine, providing accurate travel-based proximity. HAVERSINE uses straight-line geographic distance, which is faster to calculate but less accurate for routing purposes. Default: HAVERSINE. anyOf: - $ref: '#/components/schemas/DistanceType' - type: 'null' workloadSensitivity: type: - number - 'null' format: double explanation: anyOf: - $ref: '#/components/schemas/ExplanationOptions' - type: 'null' fairComplexityPerTrip: type: - boolean - 'null' fairComplexityPerResource: type: - boolean - 'null' Weights: type: object examples: - priorityWeight: 100 workloadSpreadWeight: 10 travelTimeWeight: 1 plannedWeight: 1000 asapWeight: 5 minimizeResourcesWeight: 3600 allowedResourcesWeight: 500 waitTimeWeight: 1 urgencyWeight: 50 driveTimeWeight: 1 clusteringWeight: 1 description: OnRoute Weights properties: priorityWeight: type: - integer - 'null' format: int32 examples: - 100 description: >- Weight modifier for job priority constraints. Higher values make the solver more likely to include high-priority jobs in the solution when not all jobs can be assigned. This affects job selection probability but not scheduling order. The weight is multiplied by the job's priority value and duration. maximum: 1000 minimum: 0 workloadSpreadWeight: type: - integer - 'null' format: int32 examples: - 10 description: >- Weight modifier for workload balancing across resources and time periods. Higher values make the solver more aggressive about equalizing service time distribution. Works with fairWorkloadPerTrip and fairWorkloadPerResource options, and is sensitive to the workloadSensitivity parameter. maximum: 1000 minimum: 0 travelTimeWeight: type: - integer - 'null' format: int32 examples: - 1 description: >- Weight modifier for total travel time optimization. This is the baseline weight (typically 1) against which all other weights are compared. Higher values make the solver more aggressive about minimizing travel time, potentially at the expense of other objectives. maximum: 1000 minimum: 0 plannedWeight: type: - integer - 'null' format: int32 examples: - 1000 description: >- Weight modifier for deviations from planned arrivals and resource assignments. Higher values make the solver more reluctant to deviate from plannedArrival times and plannedResource assignments. This is crucial for maintaining customer appointments and commitments. maximum: 1000 minimum: 0 asapWeight: type: - integer - 'null' format: int32 examples: - 5 description: >- Weight modifier for scheduling jobs as early as possible within their time windows and resource availability. Higher values push jobs toward the beginning of shifts and planning periods, useful for front-loading work or maximizing completion rates. maximum: 1000 minimum: 0 minimizeResourcesWeight: type: - integer - 'null' format: int32 examples: - 3600 description: >- Weight modifier for minimizing the number of active resources per day/trip. The weight is measured in the same units as travel time - a weight of 3600 means using an additional resource is equivalent to 1 hour of travel time. Higher values encourage consolidation of jobs onto fewer resources. maximum: 1000 minimum: 0 allowedResourcesWeight: type: - integer - 'null' format: int32 examples: - 500 description: >- Weight modifier for soft violations of resource assignment constraints. When jobs have allowedResources restrictions and they cannot be satisfied as hard constraints, this weight determines the penalty for assigning jobs to non-allowed resources. maximum: 1000 minimum: 0 waitTimeWeight: type: - integer - 'null' format: int32 examples: - 1 description: >- Weight modifier for total waiting time across all resources. Waiting time occurs when resources arrive at jobs before their time windows open or when they have idle time between jobs. Higher values make the solver more aggressive about minimizing idle time. maximum: 1000 minimum: 0 urgencyWeight: type: - integer - 'null' format: int32 examples: - 50 description: >- Weight modifier for job urgency constraints. Higher values make the solver more aggressive about scheduling urgent jobs earlier in the day and planning period. This affects the sequence and timing of job execution based on their urgency values. maximum: 1000 minimum: 0 driveTimeWeight: type: - integer - 'null' format: int32 examples: - 1 description: >- Weight modifier for total driving time across all resources. Similar to travelTimeWeight but focuses specifically on driving time violations or constraints. Higher values make the solver more concerned with minimizing driving time, useful for fuel efficiency or driver fatigue management. maximum: 1000 minimum: 0 rankingWeight: type: - integer - 'null' format: int32 examples: - 10 description: >- Weight modifier for resource ranking preferences defined in job rankings. Higher values make the solver more aggressive about assigning jobs to their preferred (lower-ranked) resources, even if it increases travel time or other costs. This helps maintain service quality by using optimal resource assignments. maximum: 1000 minimum: 0 clusteringWeight: type: - integer - 'null' format: int32 examples: - 100 description: >- Weight modifier for geographic clustering constraint. Controls the penalty for route bounding box overlaps when clustering is enabled. Higher values more strongly discourage routes from overlapping in geographic space, promoting clearer territorial separation. The penalty is multiplied by this weight before being applied to the score. maximum: 10000 minimum: 0 jobProximityWeight: type: - integer - 'null' format: int32 examples: - 1000 description: >- Weight modifier for separating jobs that are geographically close to each other. When jobProximityRadius is set in options, this weight penalizes consecutive scheduling of jobs within that radius to different resources or non-consecutive scheduling. Higher values encourage grouping nearby jobs together in the same route segment. maximum: 10000 minimum: 0 depotCostWeight: type: - integer - 'null' format: int32 CostConfiguration: type: object examples: - drivingCostPerHour: 25 waitingCostPerHour: 15 distanceCostPerKm: 0.35 priorityCostPerPointPerHour: 5 preferredResourceViolationCost: 20 description: >- Cost configuration for financial-based optimization. When provided, the solver derives internal weights from these cost values, allowing optimization decisions to be expressed in monetary terms. All costs are in EUR (or your preferred currency - treated as unitless by the solver). properties: drivingCostPerHour: type: - number - 'null' format: double examples: - 25 description: >- Cost per hour of driving/travel time. Includes driver wages, vehicle depreciation, etc. Default: 25.0 EUR/hour minimum: 0 waitingCostPerHour: type: - number - 'null' format: double examples: - 15 description: >- Cost per hour of idle/waiting time. Typically lower than driving cost as it excludes fuel. Default: 15.0 EUR/hour when enabled minimum: 0 overtimeCostPerHour: type: - number - 'null' format: double examples: - 50 description: >- Cost per hour of overtime work. Usually 1.5x-2x regular hourly rate. Default: 50.0 EUR/hour minimum: 0 timeWindowViolationCostPerHour: type: - number - 'null' format: double examples: - 20 description: >- Cost per hour of deviation from customer time windows. Represents SLA penalties. Default: 20.0 EUR/hour minimum: 0 distanceCostPerKm: type: - number - 'null' format: double examples: - 0.35 description: >- Cost per kilometer driven. Includes fuel, tire wear, maintenance. Default: 0.35 EUR/km minimum: 0 priorityCostPerPointPerHour: type: - number - 'null' format: double examples: - 5 description: >- Cost per priority point per hour late. Linear calculation: priority * hours_late * this_cost. Default: 5.0 EUR minimum: 0 preferredResourceViolationCost: type: - number - 'null' format: double examples: - 20 description: >- Fixed cost when a job is not assigned to its preferred resource. Default: 20.0 EUR per violation minimum: 0 softSkillViolationCost: type: - number - 'null' format: double examples: - 15 description: >- Cost when a soft skill/tag constraint is violated. Default: 15.0 EUR per violation minimum: 0 rankingViolationCostPerRank: type: - number - 'null' format: double examples: - 5 description: >- Cost per rank deviation from optimal resource assignment. Default: 5.0 EUR per rank minimum: 0 workloadImbalanceCostFactor: type: - number - 'null' format: double examples: - 0.1 description: >- Cost factor for workload imbalance (overtime proxy). Applied to squared deviation. Default: 0.1 EUR minimum: 0 outOfRegionCostPerHour: type: - number - 'null' format: double examples: - 10 description: 'Cost per hour spent outside assigned region. Default: 10.0 EUR/hour' minimum: 0 resourceActivationCost: type: - number - 'null' format: double examples: - 100 description: >- Fixed cost for activating/using a resource (vehicle). Default uses resource.activationCost if set minimum: 0 CustomDistanceMatrices: type: object examples: - profileMatrices: CAR: '6': matrix-car-morning-123 '9': matrix-car-midday-456 '16': matrix-car-evening-789 TRUCK: '6': matrix-truck-morning-abc '9': matrix-truck-midday-def matrixServiceUrl: https://custom-matrix-service.com/api description: >- Custom distance matrix configuration for multi-profile and multi-slice scenarios properties: profileMatrices: type: - object - 'null' additionalProperties: type: object additionalProperties: type: string description: >- Map of vehicle profile names (CAR, BIKE, TRUCK) to time slice hour mappings. Each time slice hour maps to a matrix ID that should be fetched from the distance matrix service. Time slice hours correspond to: 6=MORNING_RUSH, 9=MORNING, 12=MIDDAY, 14=AFTERNOON, 16=EVENING_RUSH, 20=NIGHT. matrixServiceUrl: type: - string - 'null' description: >- Optional URL for external distance matrix service endpoint. If not provided, uses the default system service. Depot: type: object required: - name examples: - name: Depot-1 location: latitude: 51.0543 longitude: 3.7174 windows: - from: '2023-01-13T08:00:00Z' to: '2023-01-13T17:00:00Z' cost: 10 duration: 600 capacity: - 100 description: A depot or disposal site that resources can visit during their routes. properties: name: type: string examples: - Depot-1 maxLength: 255 pattern: ^(?!.*\$\{)[^<>"';`\\\x00]*$ description: Unique name of the depot location: type: - object - 'null' description: Geographical location of the depot anyOf: - $ref: '#/components/schemas/Location' - type: 'null' windows: type: - array - 'null' items: $ref: '#/components/schemas/DateWindow' description: >- Opening hours of the depot. Each window defines a time range during which the depot accepts visits. cost: type: - number - 'null' format: double examples: - 10 description: >- Per-visit cost for using this depot. Used in cost-based optimization. minimum: 0 duration: type: - integer - 'null' format: int32 examples: - 600 description: Service/unloading time at the depot in seconds. minimum: 0 capacity: type: - array - 'null' maxItems: 5 examples: - - 100 - 50 items: type: integer format: int32 description: >- Multi-dimensional capacity of the depot. Matches the load dimensions of jobs. Relation: type: object required: - type - jobs - timeInterval examples: - type: SEQUENCE jobs: - Job-1 - Job-2 resource: vehicle-1 minTimeInterval: 0 maxTimeInterval: 3600 partialPlanning: false maxWaitingTime: 1200 timeInterval: FROM_ARRIVAL tags: - urgent description: Relation between two jobs. properties: type: $ref: '#/components/schemas/RelationType' type: string pattern: \S description: >- Type of relationship constraint between jobs. SAME_TRIP: jobs must be on the same vehicle/day. SEQUENCE: jobs must be done in order with optional time intervals. DIRECT_SEQUENCE: jobs must be consecutive with no other jobs between them. NEIGHBOR: jobs must be geographically close. SAME_TIME: jobs must be done simultaneously. PICKUP_AND_DELIVERY: first job is pickup, second is delivery. SAME_RESOURCE: jobs must use the same resource. SAME_DAY: jobs must be on the same day. GROUP_SEQUENCE: jobs with matching tags must be in sequence. jobs: type: array examples: - - JOB-1 - JOB-2 items: type: string description: >- List of job names involved in this relation. For sequence-based relations, the order matters - jobs will be executed in the order specified. For other relations, order may be irrelevant. All job names must exist in the request's jobs list. resource: type: - string - 'null' examples: - vehicle-1 maxLength: 255 pattern: ^(?!.*\$\{)[^<>"';`\\\x00]*$ description: >- Optional resource constraint for this relation. When specified, all jobs in the relation must be assigned to this specific resource. This creates a hard constraint that can help enforce resource-specific workflows or capabilities. minTimeInterval: type: - integer - 'null' format: int32 examples: - 0 description: >- Minimum time interval in seconds that must pass between consecutive jobs in sequence relations. This ensures adequate time for travel, setup, or processing between related jobs. Only applies to SEQUENCE, DIRECT_SEQUENCE, and SAME_TIME relations. maxTimeInterval: type: - integer - 'null' format: int32 examples: - 3600 description: >- Maximum time interval in seconds allowed between consecutive jobs in sequence relations. This prevents excessive delays between related jobs and ensures timely completion of job sequences. Only applies to SEQUENCE, DIRECT_SEQUENCE, and SAME_TIME relations. partialPlanning: type: boolean examples: - false description: >- Allows the solver to include only some jobs from this relation in the final solution when the full relation cannot be satisfied due to constraints. When false, either all jobs in the relation are assigned or none are, maintaining the relation's integrity. maxWaitingTime: type: - integer - 'null' format: int32 examples: - 1200 description: >- Maximum waiting time in seconds between jobs in a SAME_TIME relation. This defines how much time synchronization tolerance is allowed - jobs can start within this time window of each other. Defaults to 1200 seconds (20 minutes) if not specified. timeInterval: $ref: '#/components/schemas/TimeInterval' type: string description: >- Reference point for measuring time intervals between jobs in sequence relations. FROM_ARRIVAL (default) measures from when the first job's service begins to when the second job's service begins. FROM_DEPARTURE measures from when the first job's service ends to when the second job's service begins. tags: type: - array - 'null' examples: - - urgent - morning items: type: string description: >- List of tag names used to define job groups in GROUP_SEQUENCE relations. Jobs with matching tags form groups that must be executed in sequence. This allows for complex sequencing rules based on job characteristics rather than explicit job names. enforceCompatibility: type: boolean description: >- When true, enforces resource compatibility checking for SAME_TIME relations. Only compatible resources can work together on linked jobs. hardMinWait: type: boolean examples: - true description: >- When true (default), the minimum time interval constraint is enforced as a hard constraint. When false, it becomes a soft constraint that can be violated with penalty. Useful for SEQUENCE and SAME_TIME relations where timing flexibility is acceptable. weight: type: - integer - 'null' format: int32 examples: - 1 description: >- Weight modifier for this relation. This can be used to modify the weight of a relation to make it more or less important than other relations. Message: type: object required: - message description: Error or warning message properties: code: type: integer format: int32 description: Error code message: type: string description: Error message Status: type: string enum: - OK - CREATED - ACCEPTED - NO_CONTENT - RESET_CONTENT - PARTIAL_CONTENT - MULTIPLE_CHOICES - MOVED_PERMANENTLY - FOUND - SEE_OTHER - NOT_MODIFIED - USE_PROXY - TEMPORARY_REDIRECT - PERMANENT_REDIRECT - BAD_REQUEST - UNAUTHORIZED - PAYMENT_REQUIRED - FORBIDDEN - NOT_FOUND - METHOD_NOT_ALLOWED - NOT_ACCEPTABLE - PROXY_AUTHENTICATION_REQUIRED - REQUEST_TIMEOUT - CONFLICT - GONE - LENGTH_REQUIRED - PRECONDITION_FAILED - REQUEST_ENTITY_TOO_LARGE - REQUEST_URI_TOO_LONG - UNSUPPORTED_MEDIA_TYPE - REQUESTED_RANGE_NOT_SATISFIABLE - EXPECTATION_FAILED - PRECONDITION_REQUIRED - TOO_MANY_REQUESTS - REQUEST_HEADER_FIELDS_TOO_LARGE - UNAVAILABLE_FOR_LEGAL_REASONS - INTERNAL_SERVER_ERROR - NOT_IMPLEMENTED - BAD_GATEWAY - SERVICE_UNAVAILABLE - GATEWAY_TIMEOUT - HTTP_VERSION_NOT_SUPPORTED - NETWORK_AUTHENTICATION_REQUIRED Shift: type: object required: - from - to examples: - from: '2023-01-13T08:00:00Z' to: '2023-01-13T17:00:00Z' start: latitude: 51.0543 longitude: 3.7174 end: latitude: 51.05 longitude: 3.72 ignoreTravelTimeToFirstJob: false ignoreTravelTimeFromLastJob: false overtimeEnd: '2023-01-13T19:00:00Z' breaks: - type: WINDOWED duration: 1800 from: '2023-01-13T12:00:00Z' to: '2023-01-13T13:00:00Z' tags: - delivery - installation description: >- Shift definition. Every potential shift of a resource should be defined here. Every shift can be a trip. properties: from: type: string format: ISO8601 datetime string examples: - '2023-01-13T08:00:00' description: 'Start of the shift datetime ' to: type: string format: ISO8601 datetime string examples: - '2023-01-13T16:00:00' description: End of the shift datetime start: type: - object - 'null' description: Start location anyOf: - $ref: '#/components/schemas/Location' - type: 'null' end: type: - object - 'null' description: End location anyOf: - $ref: '#/components/schemas/Location' - type: 'null' ignoreTravelTimeToFirstJob: type: - boolean - 'null' description: Ignore the travel time from the start location to the first order ignoreTravelTimeFromLastJob: type: - boolean - 'null' description: >- Ignore the travel time from the last order to the optional end location overtime: deprecated: true description: Can go into overtime. overtimeEnd: type: - string - 'null' format: ISO8601 datetime string examples: - '2022-03-10T12:15:50-04:00' description: Maximum overtime time. breaks: type: - array - 'null' items: $ref: '#/components/schemas/BreakDto1' description: Windowed breaks definitions. tags: type: - array - 'null' items: type: string description: >- Shift tags will ensure that this resource can only do Jobs of this tag during this shift. This allows for tag based availability. jobTypeLimitations: type: - object - 'null' examples: - Initial Appointment: 2 Wound Care: 1 additionalProperties: type: integer format: int32 description: >- Map of job type to maximum count allowed per shift. Null means no limitations. Location: type: object description: Geographical Location in WGS-84 properties: latitude: type: number format: double examples: - 50.0987624 description: Latitude longitude: type: number format: double examples: - 4.93849204 description: Longitude h3Index: type: - integer - 'null' format: int64 examples: - 617700169958293500 description: H3 hexagon index at resolution 9 (optional) Category: type: string enum: - CAR - BIKE - TRUCK examples: - CAR description: Transportation type for the resource Rule: type: object examples: - period: from: '2024-01-01T08:00:00Z' to: '2024-01-07T17:00:00Z' minWorkTime: 14400 maxWorkTime: 28800 minServiceTime: 7200 maxServiceTime: 21600 minDriveTime: 3600 maxDriveTime: 10800 jobTypeLimitations: Install: 10 groupTag: contractor-install-pool description: Periodic time rule for a resource properties: period: type: object description: Period of the rule. If null, then it encompasses the entire period. anyOf: - $ref: '#/components/schemas/PeriodDto' - type: 'null' minWorkTime: type: - integer - 'null' format: int32 description: >- Minimum work time in seconds. Work time is service time + drive/travel time. maxWorkTime: type: - integer - 'null' format: int32 description: >- Maximum work time in seconds. Work time is service time + drive/travel time. minServiceTime: type: - integer - 'null' format: int32 description: Minimum service time in seconds maxServiceTime: type: - integer - 'null' format: int32 description: Maximum service time in seconds minDriveTime: type: - integer - 'null' format: int32 description: Minimum drive time in seconds maxDriveTime: type: - integer - 'null' format: int32 description: Maximum drive time in seconds minJobComplexity: type: - integer - 'null' format: int32 description: >- Sum of the complexity of the jobs completed by this resource should reach this value maxJobComplexity: type: - integer - 'null' format: int32 description: >- Sum of the complexity of the jobs completed by this resource should not go over this value jobTypeLimitations: type: - object - 'null' examples: - Initial Appointment: 10 Wound Care: 5 additionalProperties: type: integer format: int32 description: >- Map of job type to maximum count allowed per period. Null means no limitations. groupTag: type: - string - 'null' description: >- Optional pool identifier. When set, this rule is not per-resource: it applies as a single shared bound across every resource that declares a rule with the same groupTag. The customer chooses the value freely (it is not related to Resource.tags). Resources opt into the pool by each declaring an identical rule (same period and same field values). The first declaration encountered defines the pool; any subsequent declaration with mismatched period or fields is excluded from the pool with a warning, and its resource simply does not participate. A pool with one declaring resource behaves like a per-resource rule. A resource may belong to multiple pools by declaring multiple rules with different groupTags. Tag: type: object required: - name examples: - name: certified-technician hard: false weight: 300 description: A tag is a match between a `Job` and a `Resource`. properties: name: type: string examples: - certified-technician maxLength: 255 pattern: ^(?!.*\$\{)[^<>"';`\\\x00]*$ description: >- Tag name that defines a skill, capability, or requirement. This creates a matching constraint between jobs and resources - only resources with this tag can be assigned to jobs that require it. Common examples include 'plumbing', 'electrical', 'certified-technician', or 'heavy-lifting'. hard: type: - boolean - 'null' examples: - false description: >- Constraint type for this tag requirement. When true (default), creates a hard constraint - jobs can only be assigned to resources with matching tags. When false, creates a soft constraint - jobs prefer resources with matching tags but can be assigned to others if needed, with a score penalty. default: true weight: type: - integer - 'null' format: int32 examples: - 300 description: >- Penalty weight applied when this tag constraint is violated (soft constraints only). The weight is measured in the same units as travel time - a weight of 3600 means violating this tag constraint is equivalent to 1 hour of additional travel time. Higher weights make the constraint more important. Ranking: type: object required: - name examples: - name: certified-technician ranking: 5 description: A ranking is a measure of the affinity of a `Resource` towards a `Job`. properties: name: type: string examples: - vehicle-1 maxLength: 255 pattern: ^(?!.*\$\{)[^<>"';`\\\x00]*$ description: >- Name of the resource being ranked for this job. Must exactly match a resource name defined in the request's resources list. This creates a preference relationship between the job and the specified resource. ranking: type: - integer - 'null' format: int32 examples: - 5 description: >- Preference ranking score for this resource (1-100). Lower values indicate stronger preference - rank 1 is most preferred, rank 100 is least preferred. The solver will try to assign jobs to higher-ranked (lower-numbered) resources when possible, with the preference strength controlled by the rankingWeight in the weights configuration. maximum: 100 minimum: 1 Proficiency: type: object required: - resource examples: - resource: senior-technician durationModifier: 0.8 description: >- Defines how efficiently a specific resource can complete a job. The durationModifier adjusts the job's effective service time when assigned to that resource. properties: resource: type: string examples: - senior-technician maxLength: 255 pattern: ^(?!.*\$\{)[^<>"';`\\\x00]*$ description: >- Name of the resource whose proficiency is being defined. Must exactly match a resource name defined in the request's resources list. durationModifier: type: number format: float examples: - 0.8 description: >- Multiplier applied to the job's duration when assigned to this resource. Values less than 1.0 reduce the duration (faster completion), values greater than 1.0 increase it (slower completion). For example, 0.8 means the resource completes the job 20% faster, 1.5 means 50% slower. Default is 1.0 (no modification). default: 1 DateWindow: type: object required: - from - to examples: - from: '2024-01-15T09:00:00Z' to: '2024-01-15T17:00:00Z' hard: true weight: 1 description: Window in which the job can be executed properties: from: type: string format: ISO8601 datetime string examples: - 2023-01-13T08:00 description: Date time start of window to: type: string format: ISO8601 datetime string examples: - 2023-01-18T12:00 description: Date time end of window weight: type: - integer - 'null' format: int32 examples: - 1 description: Weight constraint modifier default: 1 hard: type: - boolean - 'null' examples: - true description: Hard constraint violation of DateWindow default: true RoutingEngine: type: string enum: - OSM - TOMTOM - GOOGLE - ANYMAP examples: - OSM description: The routing engine to use for distance and travel time calculations DistanceType: type: string enum: - REAL - HAVERSINE examples: - HAVERSINE description: The type of distance calculation to use for job proximity calculations ExplanationOptions: type: object examples: - enabled: true filterHardConstraints: true description: Options to manage the explanation of the solution properties: enabled: type: - boolean - 'null' examples: - true description: >- When enabled the explanation will contain a map of all the alternative positions for each job filterHardConstraints: type: - boolean - 'null' examples: - true description: >- When true the map of alternative positions will contain only feasible alternatives onlyUnassigned: type: - boolean - 'null' RelationType: type: string enum: - SAME_TRIP - SEQUENCE - DIRECT_SEQUENCE - SAME_TIME - NEIGHBOR - PICKUP_AND_DELIVERY - SAME_RESOURCE - SAME_DAY - GROUP_SEQUENCE examples: - SEQUENCE description: Type of relation between jobs TimeInterval: type: string enum: - FROM_ARRIVAL - FROM_DEPARTURE examples: - FROM_ARRIVAL description: >- Determines if the time interval between jobs should be measured from arrival or departure BreakDto1: type: object required: - type properties: type: $ref: '#/components/schemas/BreakType' PeriodDto: type: object required: - start - end - from - to examples: - from: '2024-01-01T08:00:00Z' to: '2024-01-07T17:00:00Z' description: Subset of the planning period properties: from: $ref: '#/components/schemas/ZonedDateTime' type: string examples: - '2007-12-01T08:00:00' description: 'Start date-time ' end: examples: - '2007-12-31T17:00:00' description: 'End date-time ' to: $ref: '#/components/schemas/ZonedDateTime' BreakType: type: string enum: - WINDOWED - DRIVE - UNAVAILABILITY examples: - WINDOWED description: Type of break that can be defined for a resource ZonedDateTime: type: string format: date-time examples: - '2022-03-10T12:15:50-04:00' securitySchemes: apikey: type: apiKey description: Api Key based authentication (apikey) name: Authorization in: header ````