schedule

A schedule represents a recurring job that must be serviced at regular intervals.

For example, a customer might need frozen food supplies delivered once a week. The actual day of the delivery does not matter as long as food is delivered every five to eight days. By allowing the optimizer to choose the delivery day (the base_date), RouteCloud can produce more efficient routes by placing nearby deliveries on the same day. The above example can be defined as follows:

{
  "id": "schedule0",
  "type": "weekly",
  "earliest_date": "2016-5-15",
  "allowed_variance_before": 1,
  "allowed_variance_after": 1,
  "jobs": [ "job0", "job1", "job2" ]
}
Name Type Description
allowed_days_of_week day_of_week[] The days of the week that the schedule can be delivered on. If null, then all days of the week are allowed. Defaults to null.
allowed_variance_after integer How many days the delivery can be made after the usual delivery day. Defaults to 0.
allowed_variance_before integer How many days the delivery can be made before the usual delivery day. Defaults to 0.
base_date date Base date. Can be used to specify that a schedule is delivered, for example, every Wednesday or on the 11th of each month. If not set, RouteCloud chooses the base date for the schedule.
earliest_date date Earliest date. The schedule will not be delivered before this date. Required for instantiate requests. If null, the date of the earliest route is used.
frequency integer How many times the customer is serviced per period (for times_per_week, times_per_month, and times_per_year). Defaults to 1.
id id Unique ID of the schedule.
interval integer How often the customer is serviced; for example, every two weeks (for daily, weekly, monthly_by_day_of_week, and monthly_by_day_of_month). Defaults to 1.
job_overrides schedule_job_override[] An array containing ordinals that should not be instantiated.
job_template job_template A template for the recurring jobs to be instantiated from this schedule.
jobs job[] or id[] List of job IDs that belong to the schedule, starting from the earliest_date. A null job means that the delivery is skipped.
latest_date date Latest date. The schedule will not be delivered after this date. If null, the schedule will recur forever. Defaults to null.
name string Optional. The name of the schedule.
type string The recurrence type of the schedule. Can be: one_off, daily, weekly, monthly_by_day_of_week, monthly_by_day_of_month, times_per_week, times_per_month, or times_per_year.

schedule_job_override

A schedule_job_override object is used with the instantiate endpoint to instruct the RouteCloud API to skip a specified ordinal when instantiating jobs. This is useful if a job that falls within the instantiate period has already been delivered earlier due to variance.

Name Type Description
ordinal integer The ordinal in schedule.jobs to be skipped.
type string The type of override. Must have the value out_of_range.

Example

{
  {
    "id": "schedule0 - every week on the same day",
    "type": "weekly"
  },
  {
    "id": "schedule1 - every week on a Monday (note that 2016-05-16 is a Monday)",
    "type": "weekly",
    "base_date": "2016-05-16" 
  },
  {
    "id": "schedule2 - every week on a Monday or Tuesday (note that 2016-05-16 is a Monday)",
    "type": "weekly",
    "base_date": "2016-05-16", 
    "allowed_variance_after": 1
  },
  {
    "id": "schedule3 - twice a month, with each delivery within 2 days of the previous months delivery",
    "type": "times_per_month",
    "frequency": 2,
    "allowed_variance_before": 2,
    "allowed_variance_after": 2
  },
  {
    "id": "schedule4 - every 2 weeks on the same day",
    "type": "weekly",
    "interval": 2,
  },
  {
    "id": "schedule5 - twice per week, only on week days",
    "type": "times_per_week",
    "frequency": 2,
	"allowed_days_of_week": [ "mon", "tue", "wed", "thu", "fri" ]
  },
}

Using earliest_date and base_date

The earliest_date specifies when a schedule can start without constraining the days each job can be placed on. The base_date specifies the days each job can be placed on, but not when the schedule starts. For example, the following weekly schedule has three deliveries; one during the first week of May, one during the second week, and one during the third week:

{
  "id": "schedule0",
  "type": "weekly",
  "earliest_date": "2016-05-01",
  "jobs": [ "job0", "job1", "job2" ]
}

If a base_date on a Monday (for example, May 16) is added, the three deliveries will be on the first, second, and third Monday of the month:

{
  "id": "schedule0",
  "type": "weekly",
  "earliest_date": "2016-05-01",
  "base_date": "2016-05-16",
  "jobs": [ "job0", "job1", "job2" ]
}

The deliveries in the example above will take place on 2016-05-02, 2016-05-09, and 2016-05-16, even though the base_date is later in the month.

Using monthly_by_day_of_month and monthly_by_day_of_week

For the monthly_by_day_of_month schedule type, a base_date of 2016-05-16 means that the schedule is delivered on the 16th day of each month. For the monthly_by_day_of_week schedule type, a base_date of 2016-05-16 means that the schedule is delivered on the third Monday of each month.

See Also