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

~/Downloads/Mileage Logger/Timeline.json

3) Install dependencies

# in your chosen venv/conda env
pip install -r requirements.txt

4) Run (monthly workflow: previous calendar month, weekdays only)

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:

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:

mileage

---

Installing

Windows (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

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

---

Configuration

config/sites.yml

Define your whitelisted locations.

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

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)

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:

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).

---