Period Rules

Overview

Period rules enable you to set operational constraints that apply across all shifts for a resource. These rules ensure compliance with regulations, safety requirements, and operational policies by limiting or requiring specific work patterns.

Period rules are particularly useful for implementing driver regulations, union agreements, and safety policies that span multiple shifts.

Available Rule Types

Drive Time Rules

Control the amount of time resources spend driving:

integer

Maximum driving time in seconds allowed during the period

integer

Minimum driving time in seconds required during the period

Work Time Rules

Manage total working hours:

integer

Maximum total work time in seconds (includes driving and service time)

integer

Minimum total work time in seconds required

Use minimum drive time rules cautiously. They may force the solver to create longer routes than necessary to meet the minimum requirement.

Implementation Example

This example demonstrates how a maximum drive time rule affects route planning:

Request
Solution
Analysis

{
  "resources": [
    {
      "name": "R-1",
      "start": {
        "latitude": 50.923554431590595,
        "longitude": 4.890691212789399
      },
      "shifts": [
        {
          "from": "2023-01-13T08:00:00",
          "to": "2023-01-13T22:00:00"
        }
      ],
      "rules": [
        {
          "period": { "from": "2023-01-13T00:00:00", "to": "2023-01-14T00:00:00" },
          "maxDriveTime": 10000  // ~2.78 hours max driving
        }
      ]
    }
  ],
  "jobs": [
    {
      "name": "JOB-1",
      "location": {
        "latitude": 50.54963315022148,
        "longitude": 4.848855475505483
      },
      "duration": 3600
    },
    {
      "name": "JOB-2",
      "location": {
        "latitude": 50.65910297910443600,
        "longitude": 4.007987934186738
      },
      "duration": 3600
    },
    // Jobs 3-10 with various locations...
  ],
  "options": {
    "partialPlanning": true
  }
}

{
  "score": {
    "hardScore": 0,
    "mediumScore": -25200,
    "softScore": -6924,
    "feasible": true
  },
  "trips": [
    {
      "visits": [
        {
          "arrival": "2023-01-13T08:44:54",
          "job": "JOB-6",
          "location": {
            "latitude": 50.89633806889935,
            "longitude": 4.45161298168845
          }
        },
        {
          "arrival": "2023-01-13T10:21:25",
          "job": "JOB-5",
          "location": {
            "latitude": 50.94837893617721,
            "longitude": 4.001604640663746
          }
        },
        {
          "arrival": "2023-01-13T11:55:17",
          "job": "JOB-10",
          "location": {
            "latitude": 50.78868282668716,
            "longitude": 4.167956383823208
          }
        }
      ],
      "resource": "R-1",
      "date": "2023-01-13",
      "departureTime": "2023-01-13T08:00:00",
      "travelTime": 6917,     // Under 10000 second limit
      "workTime": 17717,
      "serviceTime": 10800
    }
  ],
  "unserved": [
    "JOB-1", "JOB-2", "JOB-3", "JOB-4", 
    "JOB-7", "JOB-8", "JOB-9"
  ],
  "status": "SOLVED"
}

Common Rule Patterns

Standard Driver Regulations

European driving regulations:

{
  "rules": [
    {
      "period": { "from": "2023-01-13T00:00:00", "to": "2023-01-14T00:00:00" },
      "maxDriveTime": 32400,    // 9 hours daily driving
      "maxWorkTime": 50400       // 14 hours total work
    }
  ]
}

Minimum Utilization Requirements

Ensure resources meet minimum productivity:

{
  "rules": [
    {
      "period": { "from": "2023-01-13T00:00:00", "to": "2023-01-14T00:00:00" },
      "minWorkTime": 21600,      // Minimum 6 hours work
      "maxWorkTime": 36000       // Maximum 10 hours work
    }
  ]
}

Combined Rules

Multiple rules work together:

{
  "rules": [
    {
      "period": { "from": "2023-01-13T00:00:00", "to": "2023-01-14T00:00:00" },
      "maxDriveTime": 25200,     // Max 7 hours driving
      "minDriveTime": 7200,      // Min 2 hours driving
      "maxWorkTime": 36000,      // Max 10 hours total
      "minWorkTime": 14400       // Min 4 hours total
    }
  ]
}

Rule Scope and Application

Period Definition

Each rule’s period is an explicit { "from", "to" } date-time window that you compute and pass in yourself — there is no rolling DAY/WEEK/MONTH keyword and the solver does not derive “today” or “this week” on your behalf. If period is omitted (null), the rule encompasses the entire planning period, spanning all of a resource’s shifts:

{
  "shifts": [
    {"from": "2023-01-13T08:00:00", "to": "2023-01-13T12:00:00"},
    {"from": "2023-01-13T13:00:00", "to": "2023-01-13T17:00:00"}
  ],
  "rules": [
    {
      "period": { "from": "2023-01-13T00:00:00", "to": "2023-01-14T00:00:00" },
      "maxDriveTime": 18000  // Applies across BOTH shifts on that day
    }
  ]
}

Multi-Day Planning

For multi-day scenarios, a rule only applies to the exact window given in its period — it does not automatically reset each day. To cap driving on each individual day, declare one rule per day, each with its own period:

{
  "shifts": [
    {"from": "2023-01-13T08:00:00", "to": "2023-01-13T17:00:00"},
    {"from": "2023-01-14T08:00:00", "to": "2023-01-14T17:00:00"}
  ],
  "rules": [
    {
      "period": { "from": "2023-01-13T00:00:00", "to": "2023-01-14T00:00:00" },
      "maxDriveTime": 25200  // Limit for day 1 only
    },
    {
      "period": { "from": "2023-01-14T00:00:00", "to": "2023-01-15T00:00:00" },
      "maxDriveTime": 25200  // Limit for day 2 only
    }
  ]
}

Best Practices

Start with regulatory requirements

Implement legally required limits first (e.g., DOT hours of service, EU driving time regulations).

Add operational constraints

Layer in company policies and union agreements after regulatory compliance.

Test with partial planning

Enable partialPlanning: true when rules might prevent full job assignment.

Monitor rule impact

Use the explanation API to understand how rules affect job assignments.

Balance min/max rules

Avoid overly restrictive combinations that create infeasible scenarios.

Troubleshooting

Too Many Unassigned Jobs

If rules cause excessive unassigned jobs:

Solution strategies

Review rule strictness: Are limits realistic for your operation?
Add more resources: Distribute work across more vehicles
Adjust job locations: Cluster jobs to reduce travel
Extend shift times: Provide more working hours within rules
Use soft constraints: Consider making some rules soft with penalties

Inefficient Routes

When minimum rules force unnecessary travel:

Replace minimum drive time rules with minimum job count or revenue targets to achieve utilization goals without forcing inefficient routing.

Advanced Scenarios

Time-Based Rule Variations

While not directly supported, you can simulate time-based variations using multiple resources:

{
  "resources": [
    {
      "name": "Driver-Morning",
      "shifts": [{"from": "2023-01-13T06:00:00", "to": "2023-01-13T14:00:00"}],
      "rules": [{
        "period": { "from": "2023-01-13T00:00:00", "to": "2023-01-14T00:00:00" },
        "maxDriveTime": 25200
      }]  // 7 hours
    },
    {
      "name": "Driver-Evening", 
      "shifts": [{"from": "2023-01-13T14:00:00", "to": "2023-01-13T22:00:00"}],
      "rules": [{
        "period": { "from": "2023-01-13T00:00:00", "to": "2023-01-14T00:00:00" },
        "maxDriveTime": 21600
      }]  // 6 hours (different limit)
    }
  ]
}

Combining with Other Constraints

Rules work alongside other VRP features:

{
  "resources": [{
    "name": "R-1",
    "rules": [{
      "period": { "from": "2023-01-13T00:00:00", "to": "2023-01-14T00:00:00" },
      "maxDriveTime": 28800
    }],
    "breaks": [
      {
        "type": "DRIVE",
        "duration": 2700,        // 45-min break
        "driveTime": 16200       // After 4.5 hours driving
      }
    ],
    "maxDriveDistance": 300000   // 300km daily limit
  }]
}

Performance Impact

Period rules are evaluated continuously during optimization. Complex rule combinations may increase solve time, especially with tight constraints that limit feasible solutions.

Consider:

Fewer, simpler rules perform better than many complex rules
Hard rules that severely limit options increase computation time
Partial planning helps when rules make full assignment impossible

Breaks

Configure mandatory rest periods within shifts

Shift Management

Define when resources are available to work

Resource Constraints

Set capacity, skills, and regional limitations

Weights

Fine-tune how rules impact optimization

Platform

VRP API

Fill API

Overview

Available Rule Types

Drive Time Rules

Work Time Rules

Implementation Example

Common Rule Patterns

Standard Driver Regulations

Minimum Utilization Requirements

Combined Rules

Rule Scope and Application

Period Definition

Multi-Day Planning

Best Practices

Troubleshooting

Too Many Unassigned Jobs

Inefficient Routes

Advanced Scenarios

Time-Based Rule Variations

Combining with Other Constraints

Performance Impact

Breaks

Shift Management

Resource Constraints

Weights

​Overview

​Available Rule Types

​Drive Time Rules

​Work Time Rules

​Implementation Example

​Common Rule Patterns

​Standard Driver Regulations

​Minimum Utilization Requirements

​Combined Rules

​Rule Scope and Application

​Period Definition

​Multi-Day Planning

​Best Practices

​Troubleshooting

​Too Many Unassigned Jobs

​Inefficient Routes

​Advanced Scenarios

​Time-Based Rule Variations

​Combining with Other Constraints

​Performance Impact

​Related Features

Breaks

Shift Management

Resource Constraints

Weights

Overview

Available Rule Types

Drive Time Rules

Work Time Rules

Implementation Example

Common Rule Patterns

Standard Driver Regulations

Minimum Utilization Requirements

Combined Rules

Rule Scope and Application

Period Definition

Multi-Day Planning

Best Practices

Troubleshooting

Too Many Unassigned Jobs

Inefficient Routes

Advanced Scenarios

Time-Based Rule Variations

Combining with Other Constraints

Performance Impact

Related Features