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

# Overview

> Unified transport cost and time predictions for U.S. domestic routes

**airTravelModel** is a Python library that predicts transportation cost and travel time across U.S. domestic routes — air, drive, bus, and train — through a single unified API.

## What it does

Given an origin and destination (airport codes, city names, or coordinates), `TransportPredictor` returns fare and time estimates for every transport mode, using ensemble ML models trained on real schedule and ticket data.

```python theme={null}
from air_travel_model import TransportPredictor

tp = TransportPredictor()
results = tp.predict_all("CHS", "ROA", quarter=2)
# {
#   "air_fare":   291.81,   # USD
#   "air_time":    59.0,    # minutes
#   "drive_time": 454.0,    # minutes
#   "drive_fare":  46.25,   # USD
# }
```

## Models at a glance

| Mode       | Output                            | R²   | Training data        |
| ---------- | --------------------------------- | ---- | -------------------- |
| Air fare   | Economy / business fare (USD)     | 0.92 | BTS DB1B 2023–2025   |
| Air time   | Block time (minutes)              | 0.94 | BTS T-100 2023–2025  |
| Drive time | Door-to-door drive time (minutes) | 0.99 | OSRM / OpenStreetMap |
| Drive fare | Fuel cost estimate (USD)          | —    | Formula-based        |
| Bus fare   | Intercity fare (USD)              | —    | Calibrated heuristic |
| Bus time   | Intercity travel time (minutes)   | —    | Calibrated heuristic |
| Train time | Amtrak travel time (minutes)      | 0.99 | Amtrak GTFS          |

All models fall back gracefully to calibrated heuristics for routes outside the training distribution.

## Design

* **Single entry point**: `TransportPredictor` — no need to import individual predictors.
* **Ensemble architecture**: each trained model is either HistGradientBoosting, RandomForest, or an average ensemble — whichever scored best on validation.
* **Graceful degradation**: `predict()` uses ML with OSRM/heuristic fallbacks; `estimate()` always returns a value.
* **Mountainous terrain aware**: drive time for routes not in training data queries OSRM live rather than using straight-line (haversine) distance, which would dramatically underestimate travel time on winding mountain roads.
* **Extensible**: abstract `BaseTrainer` / `BasePredictor` make it straightforward to add new modes.