🧠 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

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

🚀 Quick Start

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

{
  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

{
  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

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 ❤️