smarteta/README.md

Smart urban ETA estimator based on time, distance, vehicle type and real-world corrections

# 🧠 smart-eta

**Smart ETA Estimator for Urban and Intercity Deliveries**

Estimate average travel times in minutes between two GPS coordinates based on:
- 🚗 Vehicle type (car / scooter)
- 🕒 Time of day
- 📅 Day of the week
- 📏 Distance impact
- 🚥 Urban delays (traffic lights, parking)
- 📊 Optional real-world data for calibration
- 🔄 Smart urban/intercity classification

---

## ✨ Features

- ✅ Works entirely offline – no API calls!
- 🚴‍♂️ Optimized for delivery use cases inside cities
- 📉 Learns from historical data and self-calibrates
- 🧠 Understands how real-world urban traffic behaves
- 📦 Lightweight and easy to integrate

---

## 📦 Installation

```bash
npm install smart-eta
# or
pnpm add smart-eta
# or
yarn add smart-eta
```

---

## 🚀 Quick Start

```ts
import { estimateSmartETA } from 'smart-eta';

const result = estimateSmartETA({
  startLat: 31.25181,
  startLng: 34.7913,
  endLat: 31.2452,
  endLng: 34.7928,
  vehicleType: 'scooter'
});

console.log(result);
// { min: 2.5, avg: 3.1, max: 3.8 }
```

---

## 📘 API Reference

### `estimateSmartETA(input: EstimateInput): EstimateResult`

#### EstimateInput

| Field           | Type                            | Description                                      |
|----------------|----------------------------------|--------------------------------------------------|
| `startLat`      | `number`                        | Start point latitude                            |
| `startLng`      | `number`                        | Start point longitude                           |
| `endLat`        | `number`                        | End point latitude                              |
| `endLng`        | `number`                        | End point longitude                             |
| `vehicleType`   | `'car'` \| `'scooter'`          | Type of vehicle used                            |
| `now?`          | `Date`                          | Optional. Defaults to current system time       |
| `urban?`        | `boolean`                       | Optional override for urban/intercity logic     |
| `historicalData?` | `HistoricalEntry[]`           | Optional array of real-world ETA samples        |

#### EstimateResult

```ts
{
  min: number;  // Lower bound (90% of avg or at least 2 min)
  avg: number;  // Average estimated travel time
  max: number;  // Upper bound (110% of avg or at least 2.1 min)
}
```

#### HistoricalEntry

```ts
{
  fromLat: number;
  fromLng: number;
  toLat: number;
  toLng: number;
  actualMinutes: number;
}
```

---

## 📈 How Accuracy Works

Internally, the ETA is affected by:

1. **Base speed** (by hour + vehicle type)
2. **Day of week** (Wednesday–Thursday are slower)
3. **Short-distance penalty** (under 2km)
4. **Parking & traffic light buffer** (car vs scooter)
5. **Minimum enforced time** (2 min floor)
6. **Historical data regression** (optional)
7. **Urban/intercity auto-detection** by effective speed
8. **Urban = ×2 / Intercity = ×0.8 correction factor**
9. **±10% margin of uncertainty**

---

## 🔬 Example with Historical Data

```ts
const eta = estimateSmartETA({
  startLat: 31.25,
  startLng: 34.79,
  endLat: 31.24,
  endLng: 34.80,
  vehicleType: 'car',
  historicalData: [
    {
      fromLat: 31.25,
      fromLng: 34.79,
      toLat: 31.24,
      toLng: 34.80,
      actualMinutes: 5.2
    },
    {
      fromLat: 31.26,
      fromLng: 34.81,
      toLat: 31.23,
      toLng: 34.77,
      actualMinutes: 6.0
    }
  ]
});
```

---

## 🛠 Use Cases

- Logistics & delivery apps
- Courier ETA prediction
- Route simulations
- Driver performance analysis

---

## 🧪 Future Ideas

- 📡 Integration with real-time traffic APIs (optional)
- 📍 Auto-detect urban zones from OSM boundaries
- 🔁 Learning-based adaptive weighting from live data

---

## ⚖ License

MIT – use freely, improve openly, attribute respectfully ❤️