Metadata-Version: 2.4
Name: location-tracker
Version: 1.0.0
Summary: Self-hosted location tracking dashboard with encrypted cookies, SQLite storage, and adaptive polling
Project-URL: Homepage, https://github.com/dcondrey/location-tracker
Project-URL: Repository, https://github.com/dcondrey/location-tracker
Project-URL: Issues, https://github.com/dcondrey/location-tracker/issues
Author-email: David Condrey <davidcondrey@me.com>
License-Expression: MIT
License-File: LICENSE
Keywords: dashboard,geolocation,google-maps,location,self-hosted,tracking
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.11
Requires-Dist: cryptography>=44.0
Requires-Dist: flask>=3.1.0
Requires-Dist: folium>=0.20.0
Requires-Dist: locationsharinglib>=5.0.3
Requires-Dist: pandas>=3.0.3
Requires-Dist: playwright-stealth>=2.0.3
Requires-Dist: playwright>=1.60.0
Requires-Dist: schedule>=1.2.2
Provides-Extra: build
Requires-Dist: pyinstaller>=6.0; extra == 'build'
Provides-Extra: dev
Requires-Dist: pip-audit>=2.7; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.11; extra == 'dev'
Description-Content-Type: text/markdown

# Location Tracker

A self-hosted location tracking dashboard that polls Google Maps location sharing and visualizes movement history on an interactive map. Runs as a background daemon with a real-time web interface.

## Features

- **Real-time tracking** -- Polls Google Maps shared locations with adaptive intervals (15s when driving, 10min when stationary)
- **Interactive dashboard** -- Dark-themed Leaflet map with path visualization, heatmaps, stop detection, and timeline scrubbing
- **Self-tracking** -- Track your own position via browser geolocation
- **Encrypted cookie storage** -- Google auth tokens encrypted at rest with Fernet; key stored in macOS Keychain
- **Auto cookie refresh** -- Headless browser automatically re-authenticates when cookies expire
- **SQLite storage** -- Location history stored in an indexed SQLite database with WAL mode
- **Mobile responsive** -- Bottom-sheet sidebar on phones, touch-friendly controls
- **Multiple export formats** -- JSON, CSV, and GeoJSON
- **Persistent daemon** -- Optional launchd integration to survive reboots
- **CLI query tools** -- Look up anyone's latest location or history from the terminal

## Quick Start

```bash
# Clone and set up
git clone https://github.com/dcondrey/location-tracker.git
cd location-tracker
./setup.sh

# Or manually:
uv sync
uv run location-tracker setup

# Configure your Google account
uv run location-tracker config --email you@gmail.com

# Authenticate with Google (opens browser)
uv run location-tracker cookies

# Start tracking
uv run location-tracker on
```

The dashboard will be available at **http://tracker** (or `http://localhost:7070` if DNS isn't configured).

## Prerequisites

- **Python 3.11+**
- **macOS** (uses Keychain for cookie encryption, launchd for persistence)
- **uv** package manager ([install](https://docs.astral.sh/uv/getting-started/installation/))
- A Google account with [location sharing](https://support.google.com/maps/answer/7326816) enabled

## Commands

### Core

| Command | Description |
|---------|-------------|
| `on` | Start the tracker daemon and web dashboard |
| `off` | Stop the tracker |
| `status` | Check if the tracker is running |
| `cookies` | Open browser to authenticate with Google |
| `test` | Verify cookies are valid and list shared contacts |

### Configuration

| Command | Description |
|---------|-------------|
| `config --email you@gmail.com` | Set the Google account email |
| `config` | Show current configuration |
| `setup` | First-time setup: install Chromium, configure DNS and port forwarding |
| `dns` | Set up `http://tracker` hostname |
| `dns --remove` | Remove hostname and port forwarding |
| `install` | Install as a launchd service (auto-start on login) |
| `install --remove` | Remove the launchd service |

### Data

| Command | Description |
|---------|-------------|
| `where <person>` | Show someone's latest known location |
| `history <person> --days 7` | Show recent location history |
| `stats` | Print tracking statistics (distance, stops, dwell time) |
| `map --days 7 --output map.html` | Generate a static HTML map |
| `purge <days>` | Delete location records older than N days |

## Dashboard

The web dashboard provides:

- **Map views** -- Road, Satellite, Hybrid, Terrain, and Dark map layers via Google/CARTO tiles
- **Visualization modes** -- Path view (color-coded routes with stop nodes), Heatmap, and Points
- **Time filtering** -- 24h, 3 days, 7 days, 30 days, 90 days, or all time
- **Timeline scrubber** -- Drag to view historical positions with date/time labels
- **Person cards** -- Click to focus; shows speed badge (Stationary/Walking/Driving/Highway)
- **Self-tracking** -- Enable browser geolocation to appear on the map yourself
- **Export** -- Download data as JSON, CSV, or GeoJSON
- **Toast notifications** -- Visual feedback for all actions

## How It Works

### Polling

The tracker polls Google Maps location sharing via [`locationsharinglib`](https://github.com/costastf/locationsharinglib). Polling frequency adapts to detected movement speed:

| Speed | Category | Poll Interval |
|-------|----------|--------------|
| > 60 km/h | Highway | 15 seconds |
| 10-60 km/h | Driving | 30 seconds |
| 1-10 km/h | Walking | 60 seconds |
| < 1 km/h | Stationary | 10 minutes |

The person being tracked receives no notification. This is a passive read of data they have already chosen to share.

### Security

- **Cookie encryption** -- Google auth cookies are encrypted with `cryptography.Fernet` before writing to disk. The encryption key is stored in macOS Keychain, never on the filesystem.
- **Localhost only** -- The Flask server binds to `127.0.0.1`; not accessible from the network.
- **XSS protection** -- All user-controlled data is HTML-escaped before rendering.
- **Input validation** -- Lat/lon bounds checking, type coercion, and error handling on all API endpoints.
- **Atomic writes** -- SQLite with WAL mode for concurrent safety.

### Data Storage

Location history is stored in a local SQLite database (`location_history.db`) with indexed columns for fast queries. Existing `location_history.json` files are automatically migrated on first run.

## Project Structure

```
location-tracker/
  main.py            # CLI entry point and daemon management
  tracker.py         # Location polling, stats, and map generation
  dashboard.py       # Flask web server and API endpoints
  db.py              # SQLite database layer
  cookie_store.py    # Encrypted cookie storage (Fernet + Keychain)
  get_cookies.py     # Browser-based Google authentication
  templates/
    index.html       # Dashboard HTML
  static/
    style.css        # Dashboard styles
    app.js           # Dashboard JavaScript
  setup.sh           # One-command install script
  build.sh           # PyInstaller standalone build
```

## License

MIT
