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

README.md Unescape Escape

Mileage Logger