Skip to content

Driver Report

Menu Location: Reports > Shipping/Delivery > Driver Report (tips/mileage)

Access Level: Admin (no explicit role check in code)

Last Updated: 2026-07-24

Overview

The Driver Report provides weekly performance metrics for delivery routes and their assigned drivers. It tracks order counts, driver tips, route mileage, and how actual delivery timing compared to the estimates, to help manage driver efficiency and route planning.

Primary Functions:

  • View one row per route for a selected week
  • Track total tips and average tip per order on each route
  • Monitor route mileage
  • Compare actual delivery timing against the estimate (Time Difference)
  • Drill into stop-by-stop timing or a driver's multi-week performance

Page Layout

Header Section

  • Page Title: Driver Report
  • Driver Time Stats Button: Top-right button linking to the Driver Performance Analysis page
  • Week Navigation: Previous/next arrows around a week selector dropdown

Filter Controls

  • Week Selector: Dropdown of weekly cycles (rendered by printWeekSelection)
  • Submit Button: Loads data for the selected week
  • Navigation Arrows: Left/right buttons to jump to the previous/next week

Main Content Area

  • Info Callout: Explains how Time Difference is calculated
  • Results Table: One row per route with orders, tips, mileage, and Time Difference
  • DataTables: Search box, sortable columns, CSV export

On load, the page recalculates the current week's stats via updateDriverReportStats(). The first time the page is ever opened it also backfills the prior 20 weeks (gated by the driver_rep_up1 config flag so it only runs once).

Report Data & Columns

Column Description Calculation/Source
(Actions) View Stop Times button Links to driver-report-route-details.php for that route/week
Day Day of week for the route routes.day (0 = Sunday through 6 = Saturday)
Route Route name Links to admin-edit.php?table=routes&edit=<id>
Driver Assigned driver name drivers.name, joined via the latest routes_data row for the week
Orders Count of deliveries COUNT(cust_order.id) where status != 5 (excludes cancelled)
Tips Total driver tips SUM(cust_order.driver_tip), shown only when non-zero
Tips Avg Average tip per order Total Tips divided by Orders
Mileage Route distance in miles routes_data.distance (meters) converted to miles (x 0.000621371)
Time Difference Normalized deviation from estimate routes_data.est_deviation (seconds) shown in minutes

Routes with zero orders for the selected week are omitted from the table.

Time Difference Calculation

Purpose: Measure how actual delivery timing compared to the estimated arrival times, independent of a late start.

Methodology (computed in updateDriverReportStats() and stored in routes_data.est_deviation):

  1. Take the last stop on the route: actual delivery time minus its estimated arrival = last-stop deviation.
  2. Take the first stop on the route: actual delivery time minus its estimated arrival = first-stop deviation.
  3. Time Difference = last-stop deviation minus first-stop deviation.

Why Normalize:

  • If the driver starts late, the first-stop deviation captures that delay.
  • Subtracting it isolates route execution from the start-time delay.
  • The result reflects how the driver paced the route, not when they left.

Example: 

First stop:  actual delivery is +15 min vs estimate
Last stop:   actual delivery is +30 min vs estimate

Time Difference = 30 - 15 = +15 minutes
The driver fell 15 minutes further behind over the course of the route,
regardless of the late start.

Display Format:

  • Shown in minutes (est_deviation seconds divided by 60)
  • Positive = running later than estimated by the end of the route
  • Negative = pacing ahead of the estimate
  • Blank when est_deviation has not been calculated for the route

Filters & Search Options

Week Selection

Week Dropdown:

  • Lists weekly cycles via printWeekSelection
  • Defaults to the current week (getWeekId())
  • Submitting the form loads the chosen week

Navigation Arrows:

  • Left Arrow: previous week (week_id - 1 in the URL)
  • Right Arrow: next week (week_id + 1 in the URL)
  • Each reloads the page for that week

DataTables Features

Sorting:

  • Click any column header to sort
  • Default is no sorting (aaSorting: []), so rows show as queried: by day, then route name

Filtering:

  • Search box filters across columns
  • Live, case-insensitive filtering as you type

Display Length:

  • 200 rows per page (iDisplayLength: 200), which avoids pagination for most route counts

Export:

  • csv button in the table toolbar
  • Exports the currently filtered/sorted rows

Common Use Cases

Use Case 1: Weekly Driver Performance Review

Goal: Assess route timing for the week

Steps:

  1. Select the week from the dropdown
  2. Click Submit
  3. Review the Time Difference column for each route
  4. Note routes with consistently positive values (finishing later than estimated)
  5. Review Tips Avg alongside as a rough customer-satisfaction signal
  6. Click "View Stop Times" on a problem route

Tips:

  • Negative Time Difference is good (pacing ahead of the estimate)
  • Compare Mileage against Orders and timing for route efficiency

Use Case 2: Route Optimization Opportunities

Goal: Identify routes that need better planning

Steps:

  1. Select the week to analyze
  2. Sort by the Time Difference column
  3. Identify routes with the highest positive values
  4. Click the route name to review its configuration
  5. Click "View Stop Times" to see which stops fell behind

Tips:

  • Consistent delays across weeks suggest a systematic route issue
  • Variable delays suggest driver pacing
  • Check Mileage to confirm the route distance is reasonable

Use Case 3: Driver Tips Analysis

Goal: Compare tips across routes

Steps:

  1. Select the week to review
  2. Sort by the Tips Avg column
  3. Compare routes of similar size
  4. Note routes with very low averages

Tips:

  • Compare within similar route types (urban vs rural)
  • Empty Tips can simply mean no tips were recorded for that route

Use Case 4: Mileage Verification

Goal: Sanity-check route mileage against planning data

Steps:

  1. Select the week
  2. Review the Mileage column for each route
  3. Sum the miles for a driver's routes across the week

Tips:

  • Mileage comes from the route planning distance, converted from meters
  • It reflects the planned route, not GPS-tracked deviations or detours

Use Case 5: Capacity Planning for High-Volume Days

Goal: Ensure adequate coverage for busy days

Steps:

  1. Select a high-volume week
  2. Review the Orders column per route
  3. Note routes with very high counts and check their Time Difference
  4. Plan to split overloaded routes going forward

Actions & Operations

View Stop Times

Purpose: See stop-by-stop timing for a single route

Steps:

  1. Click "View Stop Times" for the route
  2. Opens driver-report-route-details.php for that route and week
  3. Review each stop's estimated vs actual delivery time

What It Shows (one row per order on the route, ordered by delivery time):

  • Order ID
  • Customer (first and last name)
  • Stop Number
  • Est. Delivery Time (cust_order.est_arrival)
  • Delivery Time (actual, cust_order.deliverytime)
  • Difference in minutes between estimate and actual

The page also includes a route dropdown to switch routes, a driver callout (photo, name, and an edit link to the driver record), and a "Match Est. With First Stop" button that shifts the estimated times to line up with the first actual delivery, making it easier to see how fast or slow the driver ran versus the estimates.

Purpose: Review a driver's performance across recent weeks

Steps:

  1. Click "Driver Time Stats" in the header
  2. Opens driver-report-driver-details.php (Driver Performance Analysis)

What It Shows (Driver Performance Overview, last 10 weeks):

  • Driver (photo and name)
  • Total Routes worked in the period
  • Avg Deviation across those routes
  • One Week column per week showing that week's route count, average deviation, and each route's deviation
  • Color coding: green = faster than estimate, orange = close to estimate, red = slower than estimate

All figures come from routes_data.est_deviation.

Export to CSV

Purpose: Download the table for external analysis

Steps:

  1. Select the week
  2. Optionally filter or sort the table
  3. Click the csv button in the table toolbar
  4. Open the file in Excel or Google Sheets

Troubleshooting

Driver Name Not Showing

Symptoms: Driver column is empty for a route.

Check:

  1. Confirm the route has a routes_data row for the selected week with a driver set
  2. Confirm the driver still exists in the drivers table

Notes:

  • On load the page backfills routes_data.driver from routes.driver_id for the current and future weeks, so a route with no driver assigned to it at all will still show blank.

Time Difference Shows Empty

Symptoms: Time Difference is blank for some routes.

Check:

  1. Confirm the route's orders have both an estimated arrival (est_arrival) and an actual delivery time (deliverytime) recorded
  2. Confirm the route was actually run, not just planned

Notes:

  • est_deviation is recalculated automatically each time the report loads. If deliveries were not confirmed (no deliverytime), the value cannot be computed and the column stays blank.

Mileage Shows Zero or Missing

Symptoms: Mileage is empty or shows 0.

Check:

  1. Confirm routes_data.distance has a value for the route/week
  2. Confirm route planning completed and saved a distance

No Data for Selected Week

Symptoms: Table is empty after selecting a week.

Check:

  1. The report omits routes with zero orders, so a week with no orders shows nothing
  2. Confirm routes are scheduled and orders exist for that week
  3. A future week with no deliveries yet will be empty
  • Driver Time Stats (driver-report-driver-details.php) - Multi-week driver performance analysis
  • Route Stop Times (driver-report-route-details.php) - Stop-by-stop timing for one route
  • Route Management (admin-edit.php?table=routes) - Configure delivery routes
  • Driver Management (admin-edit.php?table=drivers) - Manage driver records

Typical Workflow:

  1. Driver Report, identify a problem route, View Stop Times, adjust the route
  2. Driver Report, low tips or slow timing, Driver Management, review the driver

Permissions & Access

There is no explicit permission or role check in the page code. Access follows standard admin login; any admin who can reach the Reports menu can open the Driver Report and its detail pages, including the CSV export.

Best Practices

Regular Monitoring

  1. Review the Driver Report each week for the prior week
  2. Track Time Difference trends week over week
  3. Watch Tips Avg as a rough service-quality signal
  4. Export periodically for your own records

Route Optimization

  1. Investigate routes with large positive Time Differences
  2. Use View Stop Times to see which stops fell behind
  3. Adjust estimated times or stop order based on actual performance
  4. Consider splitting routes that regularly carry very high order counts

Things to Avoid

  • Don't read a single week in isolation; look for patterns across weeks
  • Don't compare very different route types (urban vs rural) head to head
  • Don't treat empty Tips as a problem; it often just means nothing was recorded

Quick Reference Card

Task Action/Location
View a week Select the week, click Submit
Previous week Click the left arrow
Next week Click the right arrow
Check route timing Review the Time Difference column
See stop details Click "View Stop Times"
Export week data Click the csv button
Compare routes Sort by Tips Avg or Time Difference
Find problem routes Sort Time Difference high to low
Driver multi-week view Click "Driver Time Stats" in the header

FAQs

What does a negative Time Difference mean?

The route paced ahead of its estimate by the end. It is generally a good sign of efficient execution.

Why is Time Difference normalized by the first stop?

It removes the effect of a late start. The first stop's deviation is subtracted from the last stop's deviation, so the number reflects how the driver paced the route rather than when they left.

How is mileage calculated?

It comes from the route planning distance (routes_data.distance, in meters) converted to miles. It represents the planned route, which may differ from GPS-tracked distance.

Why don't all routes show tips?

If Tips is empty, no driver tips were recorded for that route's orders (cust_order.driver_tip).

Can I see historical data for a specific driver?

Use the week arrows to move through past weeks, or open "Driver Time Stats" for a driver's last-10-weeks overview.

Change Log

2026-07-24

  • Grounded against driver-report.php, driver-report-route-details.php, driver-report-driver-details.php, and updateDriverReportStats()
  • Corrected menu location, columns, detail-page contents, and the Time Difference calculation
  • Removed the invented role/permission tiers (no permission check exists)

End of Documentation

For additional help, contact your system administrator or Kiva Logic support.