Mileage-Logger/README.md

# Mileage Logger

Small, reliable mileage-logging tool that ingests **Google Maps Timeline** exports from Android (device-local) and produces **one Excel workbook per month** ready for HR (EveryHR).

- Detects ordered work trips between whitelisted sites (schools, HQ, Home)
- Computes per-hop miles (route catalog → fallback straight-line)
- Writes `mileage_YYYY-MM.xlsx` with the exact columns HR needs
- Filters by date (e.g., **last month**), skips weekends, and (by default) assumes each workday starts at **Home**

---

## Quick Start

### 1) Export Timeline on your phone
Android: `Settings → Location → Location Services → Google Timeline → Export`  
Copy **`Timeline.json`** to your computer.

### 2) Put it here
```bash
~/Downloads/Mileage Logger/Timeline.json
```

### 3) Install dependencies
```bash
# in your chosen venv/conda env
pip install -r requirements.txt
```

### 4) Run (monthly workflow: previous calendar month, weekdays only)
```bash
cd ~/Downloads/Mileage\ Logger
python -m mileage_logger.cli import "Timeline.json"   --sites config/sites.yml   --routes tests/data/routes_golden.csv   --output ~/Downloads/Mileage\ Logger/output   --last-month   --weekdays-only
```

### 5) Find your Excel
Look in `output/` for files like `mileage_YYYY-MM.xlsx`.

---

## One‑word alias (Linux/macOS bash/zsh)
Add this to your `~/.bashrc` or `~/.zshrc`:
```bash
alias mileage='( cd ~/Downloads/Mileage\ Logger && python -m mileage_logger.cli import "Timeline.json"   --sites config/sites.yml   --routes tests/data/routes_golden.csv   --output ~/Downloads/Mileage\ Logger/output   --last-month   --weekdays-only )'
```
Then run:
```bash
mileage
```

---

## Installing

### Windows (PowerShell)
```powershell
# Run in PowerShell (inside your venv):
pip install -r requirements.txt
function mileage {
  Set-Location "$HOME\Downloads\Mileage Logger"
  python -m mileage_logger.cli import "Timeline.json" `
    --sites config\sites.yml `
    --routes tests\data
outes_golden.csv `
    --output "$HOME\Downloads\Mileage Logger\output" `
    --last-month `
    --weekdays-only
}
```

### macOS / Linux
```bash
pip install -r requirements.txt
# (optional) add the alias from Quick Start to your shell rc
```

---

## Configuration

### `config/sites.yml`
Define your whitelisted locations.

```yaml
sites:
  - canonical: "Home"
    label: "Home"
    lat: 52.65236
    lon: 1.26983
    radius_m: 400
    aliases: ["home", "inferred_home", "INFERRED_HOME"]

  - canonical: "Henderson Green Primary Academy"
    label: "Henderson Green Primary Academy"
    lat: 52.6565032
    lon: 1.2703586
    radius_m: 300
    aliases: ["Henderson Green", "Henderson Green Primary"]

  - canonical: "Unity SP"
    label: "Unity SP (HQ)"
    lat: 52.6067
    lon: 1.2886
    radius_m: 350
    aliases: ["WORK", "Unity SP HQ"]

  # ...other schools...
```

Tips:
- **radius_m**: start at 300–600 m for schools (device visits often pin to car parks, not building centroids).
- Add aliases you see in Timeline (e.g., `WORK`, `INFERRED_HOME`).

### `tests/data/routes_golden.csv`
Pre‑approved driving distances (miles) for common pairs.

```
origin,destination,miles
Home,Henderson Green Primary Academy,2.9
Henderson Green Primary Academy,Home,2.9
Henderson Green Primary Academy,Valley Primary Academy,1.1
Valley Primary Academy,Heartsease Primary Academy,4.7
# ...etc
```
If a pair isn’t found, the tool falls back to straight‑line (haversine) distance and rounds to 0.1 mi.

---

## CLI Usage

```bash
python -m mileage_logger.cli import TIMELINE.json   --sites config/sites.yml   --routes tests/data/routes_golden.csv   --output output   [date filter flags]   [behavior flags]
```

### Date filter flags (choose one style)
- `--last-month` — previous calendar month (e.g., run on 1 Sep → processes August)
- `--month YYYY-MM` — specific month (e.g., `--month 2025-08`)
- `--since YYYY-MM-DD` / `--until YYYY-MM-DD` — inclusive range
- `--days N` — last N days relative to today (local time)

### Behavior flags
- `--weekdays-only` — exclude Saturday/Sunday hops
- `--no-assume-home-start` — disable synthetic `Home → FirstSite` at start of day (default is ON)

---

## Output
One workbook per month present in the filtered data:
- File: `mileage_YYYY-MM.xlsx`
- Sheet: `YYYY-MM`
- Columns:
  - Date (YYYY-MM-DD)
  - Purpose (`Travel from {From} to {To} {Miles}mi`)
  - Miles (rounded to 0.1)
  - Vehicle
  - Job Role
  - From
  - To
  - Notes (empty)

---

## For another user/colleague
- Copy the whole folder.
- Edit `config/sites.yml`:
  - Update **Home** lat/lon and radius.
  - Keep schools the same unless their coverage differs.
- Update/add `tests/data/routes_golden.csv` lines for Home↔Sites if their home is different.
- Confirm the alias points to their own path.
- Run the same monthly command.

---

## Requirements
- Python 3.10+ (tested on 3.10–3.13)
- Works on Windows, macOS, Linux

### `requirements.txt`
```
python-dateutil>=2.8
pytz>=2023.3
PyYAML>=6.0
openpyxl>=3.1
geopy>=2.4
# Optional: only needed if you enable external routing APIs later
httpx>=0.27
```

---

## Makefile (optional convenience)
```make
install:
	pip install -r requirements.txt

run:
	python -m mileage_logger.cli import "Timeline.json" \		--sites config/sites.yml \		--routes tests/data/routes_golden.csv \		--output output \		--last-month \		--weekdays-only

# If you add linting/tests later:
lint:
	flake8 mileage_logger

test:
	pytest
```

Usage:
```bash
make install
make run
```

---

## Troubleshooting
- **No rows appear** — Increase `radius_m` (e.g., 400–600 m). Ensure aliases like `INFERRED_HOME`, `WORK` exist for Home/HQ.
- **Trips start mid‑day** — Ensure you didn’t pass `--no-assume-home-start`.
- **Only one workbook created** — Likely only one month had hops in the filtered range (expected with `--last-month`).
- **“Module not found” errors** — Activate the same environment you installed deps into (or reinstall with `pip install -r requirements.txt`).

---