Skip to main content

Schedule API Documentation

Overview​

The Schedule API provides scheduling functionality for both trucking and service repair operations. It handles time range calculations with industry-specific logic for travel time, legal breaks, and appointment durations.

Time Range Calculation​

Trucking Industry​

For trucking operations, the system calculates realistic schedule times accounting for:

Start Time Calculation​

  • Base Time: Appointment date/time
  • Travel Time: Calculated using:
    • Distance (from route mileage)
    • Average speed (default: 55 mph)
    • Buffer time (default: 30 minutes)
    • Pre-trip inspection (default: 15 minutes)
    • Post-trip inspection (default: 10 minutes)
  • 30-minute break: Required after 8 hours of driving
  • Additional breaks: 30 minutes for every additional 8-hour period
  • Complies with Federal Hours of Service (HOS) regulations

End Time​

  • Uses the appointment date as the delivery/pickup time

Service Repair Industry​

For service repair operations:

Start Time Calculation​

  • Preferred: Uses timeRange.start if provided
  • Fallback: Uses appointment date

End Time Calculation​

  • Preferred: Uses timeRange.end if provided
  • Fallback: Uses appointment date + default duration (configurable, default: 2 hours)

Configuration​

Schedule Configuration​

{
  "Schedule": {
    "defaultDuration": 2, // hours
    "travelTime": {
      "averageSpeed": 55, // mph for trucking, 35 for service
      "bufferTime": 30,   // minutes
      "preTrip": 15,      // minutes (trucking only)
      "postTrip": 10      // minutes (trucking only)
    },
    "legalBreaks": {
      "mandatory30MinBreak": {
        "enabled": true,
        "afterHours": 8,
        "durationMinutes": 30
      }
    }
  }
}

Accessing Configuration​

const { getFeature } = useCustomerConfig();
const defaultDuration = getFeature("Schedule.defaultDuration") || 2;

API Endpoints​

GET /api/v1/schedule​

Returns scheduled events and resources.

Query Parameters:

  • startDate (optional): Filter events from this date
  • endDate (optional): Filter events to this date

Response Structure:

{
  "events": [
    {
      "id": "event_id",
      "title": "Load #12345",
      "industryType": "trucking",
      "timeRange": {
        "start": "2024-01-15T08:00:00Z",
        "end": "2024-01-15T10:00:00Z",
        "alerts": [
          {
            "code": "hos_rest_required",
            "type": "action_required",
            "severity": "high",
            "message": "Trip exceeds the FMCSA 11-hour driving window and requires overnight rest planning.",
            "actionable": true
          }
        ],
        "warnings": [
          "Trip exceeds the FMCSA 11-hour driving window and requires overnight rest planning."
        ],
        "requiresAttention": true
      },
      "route": {
        "pickupLocation": {...},
        "dropoffLocation": {...},
        "estimatedDistance": 100
      }
    }
  ],
  "resources": [
    {
      "id": "resource_id",
      "name": "John Doe",
      "type": "driver",
      "status": "available"
    }
  ]
}

Trucking alert metadata​

For trucking events, timeRange may include additive alert metadata:

  • alerts: structured alert objects used by current dispatch UI
  • warnings: legacy warning strings kept for backward compatibility
  • requiresAttention: derived from actionable/review alerts, not from every warning string

Current alert object fields:

  • code
  • type
  • severity
  • message
  • actionable

Current alert types:

  • action_required
  • needs_review
  • data_quality
  • info

GET /api/v1/schedule/unassigned​

Returns unassigned jobs/legs and available resources.

Time Range Examples​

Trucking Example​

// Input: Leg with 100-mile route, appointment at 10:00 AM
const leg = {
  appointmentDate: "2024-01-15T10:00:00Z",
  route: { mileage: 100 }
};

// Calculation:
// - Travel time: 100 miles ÷ 55 mph = 1.82 hours = 109 minutes
// - Buffer time: 30 minutes
// - Pre-trip: 15 minutes
// - Post-trip: 10 minutes
// - Legal breaks: 0 minutes (under 8 hours)
// - Total: 164 minutes

// Result:
{
  start: "2024-01-15T07:16:00Z", // 10:00 AM - 164 minutes
  end: "2024-01-15T10:00:00Z"    // Original appointment time
}

Service Repair Example​

// Input: Job with timeRange provided
const job = {
  appointmentDate: "2024-01-15T14:00:00Z",
  timeRange: {
    start: "2024-01-15T13:30:00Z",
    end: "2024-01-15T15:30:00Z"
  }
};

// Result:
{
  start: "2024-01-15T13:30:00Z", // Use provided start time
  end: "2024-01-15T15:30:00Z"    // Use provided end time
}

Error Handling​

The system gracefully handles missing data:

  • Missing route information defaults to 0 miles
  • Missing appointment dates default to current time
  • Missing configuration values use industry defaults

Industry-Specific Features​

Trucking​

  • Hours of Service (HOS) compliance
  • Pre/post-trip inspection time
  • Long-distance travel calculations
  • Legal break requirements

Service Repair​

  • Flexible time ranges
  • Equipment setup/teardown time
  • Shorter travel distances
  • Configurable appointment durations