# Vehicles

## Understanding Vehicles in PTV OptiFlow

In PTV OptiFlow, a "vehicle" represents far more than just a physical transport unit. It's a comprehensive planning entity that captures a specific moment in time when a driver and vehicle are
available for route optimization. Each vehicle includes driver information, operational capabilities (refrigeration, hazmat handling, etc.), transport capacity, time availability windows (
deployability), start and end locations, service times, cost parameters, and routing constraints. This rich data model enables the planning engine to transform lists of orders and vehicles into
optimized routes.

## Integration Responsibility: Continuous State Management

Your source system or middleware is responsible for continuously preparing and sending vehicles to the API as a stream of planning-ready entities. Before each planning cycle, you must aggregate all
relevant information—driver assignments, current vehicle locations, shift schedules, capacity constraints, and operational capabilities—into complete vehicle objects. The Vehicle API should receive a
steady flow of these prepared vehicles, not sporadic updates. Think of it as maintaining a live inventory of available planning resources rather than one-time data uploads.

## Keeping Vehicle State Current

The API supports upsert (create/update) and delete operations, allowing you to modify vehicle information as conditions change. However, it's your responsibility to detect changes in your source
systems and push updates to the API proactively. If a driver's shift changes, a vehicle's start location updates, or capacity constraints are modified, your middleware must immediately reflect these
changes via the API. The planning engine relies on the most recent vehicle state you've provided—stale data leads to suboptimal or infeasible routes.

## Frequent Planning Requires Frequent Updates

For organizations running frequent planning cycles (hourly, multiple times per day, or on-demand), maintaining current vehicle state becomes critical. Your integration architecture should monitor
source system changes and push vehicle updates continuously, not just before planning requests. This ensures the planning engine always works with accurate, real-time data about driver availability,
vehicle locations, and operational constraints. The API is designed to handle high-frequency updates efficiently through its upsert mechanism and optimistic locking support (ETag headers).

## API Capabilities and Your Obligations

The Vehicle API provides robust capabilities: idempotent upserts via business_id, version control through weak ETags for conflict prevention, cursor-based pagination for bulk retrieval, and efficient
delete operations. These features enable reliable state synchronization, but they don't replace your obligation to maintain accurate source data. The API is a conduit, not a data quality manager.
Your middleware must implement change detection, data validation, and timely synchronization to ensure the planning engine receives complete, current vehicle information for every planning cycle.