> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wayak.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Route efficiency analysis

> Compare planned versus actual routes to identify waste and prioritize optimization opportunities

Every mile of deviation between a planned route and the actual route costs money — fuel, driver hours, and late deliveries. Most logistics teams review route performance manually, if they review it at all. Without a systematic comparison of planned versus actual, inefficiencies become invisible habits.

Wayak connects your TMS and GPS data, runs Python-powered distance and time calculations in playbooks, and delivers route efficiency dashboards that highlight exactly where your network is losing money. The agent identifies deviations, classifies root causes, and recommends specific optimizations.

***

## What you need

<CardGroup cols={2}>
  <Card title="Data sources" icon="database">
    * **TMS database** — Planned routes table with origin, destination, planned stops, planned miles, planned time, and assigned vehicle
    * **GPS/telematics feed** — Actual vehicle positions, timestamps, stop durations, and actual miles driven
  </Card>

  <Card title="Knowledge spaces" icon="book-open">
    * **Routing guidelines** — Standard operating procedures for route planning, maximum drive times, and delivery window rules
    * **Customer delivery requirements** — Specific delivery windows, access instructions, and appointment scheduling rules by customer
  </Card>
</CardGroup>

**Semantic layer:** Define these in your ontology before setting up the agent.

| Component | Name             | Definition                                                                                                    |
| --------- | ---------------- | ------------------------------------------------------------------------------------------------------------- |
| Object    | `Route`          | Maps to the TMS routes table. Represents a planned delivery route with its stops, miles, and time window      |
| Object    | `Vehicle`        | Maps to the fleet master table. Represents a truck or van with its capacity, cost rate, and driver assignment |
| Metric    | `RouteDeviation` | Percentage difference between actual miles driven and planned miles: `(actual - planned) / planned * 100`     |
| Metric    | `CostPerMile`    | Total route cost (fuel + driver wages + vehicle depreciation) divided by actual miles driven                  |
| Dimension | `DeviationCause` | Categorization: traffic, failed delivery attempt, incorrect stop sequence, unplanned stop, road closure       |

<Tip>
  See [building a semantic layer](/quickstart/build-semantic-layer) for a step-by-step guide.
</Tip>

***

## Agent setup

<Steps>
  <Step title="Create the agent">
    Go to **Agent Space** → **New agent**.

    | Field    | Value                                                        |
    | -------- | ------------------------------------------------------------ |
    | **Name** | Route Optimizer                                              |
    | **Role** | Delivery route and fleet analyst                             |
    | **Goal** | Minimize delivery costs and transit times across the network |
  </Step>

  <Step title="Set the description">
    > You optimize delivery routes and fleet utilization. When analyzing routes, always factor in distance, traffic patterns, delivery windows, vehicle capacity, and driver hours. Present route recommendations as comparisons — show the current route versus the optimized route with estimated savings. Use precise metrics (miles, hours, dollars). Flag any delivery at risk of missing its window. Never recommend routes that violate driver hours-of-service regulations.
  </Step>

  <Step title="Scope data access">
    Grant access to:

    * TMS database (routes, shipments, stops)
    * GPS/telematics feed (vehicle positions, actual miles)
    * Routing guidelines knowledge space
    * Customer delivery requirements knowledge space
    * `Route`, `Vehicle` objects and `RouteDeviation`, `CostPerMile` metrics
  </Step>

  <Step title="Add skills">
    <AccordionGroup>
      <Accordion title="Calculate route efficiency">
        **Trigger:** User asks about route performance or daily route review

        1. Pull planned route data (miles, stops, time windows) and actual GPS data (miles driven, stop times, arrival times) for the specified period.
        2. Calculate route deviation percentage for each route: planned miles versus actual miles.
        3. Calculate time deviation: planned transit time versus actual transit time.
        4. Identify routes with more than 15% deviation on miles or time.
        5. For each deviation, classify the root cause using GPS stop data: traffic delay, failed delivery attempt, incorrect stop sequence, unplanned stop, or road closure.
        6. Calculate the cost impact of each deviation: excess miles multiplied by cost per mile.
        7. Output a route efficiency table ranked by cost impact, with a flag column for underperforming routes.
      </Accordion>

      <Accordion title="Recommend route optimization">
        **Trigger:** User requests optimization suggestions or a route consistently underperforms

        1. Retrieve the historical performance data for the target route over the past 30 days.
        2. Identify the most frequent deviation causes and their average cost impact.
        3. Analyze stop sequence efficiency: calculate whether reordering stops would reduce total miles.
        4. Check delivery windows against historical traffic patterns to identify scheduling conflicts.
        5. Propose an optimized route with reordered stops, adjusted departure times, or alternative paths.
        6. Estimate the weekly savings if the optimization is adopted.
      </Accordion>
    </AccordionGroup>
  </Step>
</Steps>

***

## Automation

### Playbook: Weekly route efficiency report

<Steps>
  <Step title="Set the trigger">
    Schedule: **Every Monday at 7:00 AM**.
  </Step>

  <Step title="Build the workflow">
    1. **Query** the TMS for all completed routes in the previous 7 days.
    2. **Query** the GPS feed for actual miles, actual stop times, and arrival timestamps for each route.
    3. **Run Python analysis** to calculate:
       * Route deviation percentage for each route.
       * Total excess miles and excess cost across the fleet.
       * Deviation cause classification using GPS stop patterns.
       * Week-over-week trend in average route efficiency.
    4. **Condition:** If total excess cost exceeds \$5,000 for the week, flag the report as "action required" and highlight the top 5 most costly routes.
    5. **Aggregate** into a formatted report: fleet-level summary, route-level detail table, and trend chart.

    <Info>
      The **distance and cost calculation** step uses a Python code block to compute great-circle distances between GPS waypoints, aggregate excess miles, and multiply by the per-mile cost rate. You can customize the cost rate and deviation thresholds in the code.
    </Info>
  </Step>

  <Step title="Configure delivery">
    Send an email to the logistics operations manager with the subject line: "Weekly route efficiency — \[date]". Include the fleet summary at the top and the route detail table below. Post a summary to the `#fleet-ops` Slack channel.
  </Step>

  <Step title="Test and activate">
    Click **Run now** to test with live data, then toggle to **Active**.
  </Step>
</Steps>

***

## What's next

<CardGroup cols={2}>
  <Card title="Delivery exception management" icon="arrow-right" href="/use-cases/logistics/delivery-exception-management">
    Catch the exceptions that cause route deviations before they cascade across your network.
  </Card>

  <Card title="All logistics use cases" icon="list" href="/use-cases/logistics">
    See the full list.
  </Card>
</CardGroup>