Initial commit (clean, ignores in place)
This commit is contained in:
219
README.md
Normal file
219
README.md
Normal file
@@ -0,0 +1,219 @@
|
||||
# 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`).
|
||||
|
||||
Reference in New Issue
Block a user