🏃 Strava Intelligence

A Python toolkit for analyzing and visualizing your Strava activities without paying for Strava Premium. Sync your activities, generate cool visualizations, and track your performance metrics over time. This repository is conceived as a starting point for building more advanced Strava data analysis tools. I will keep adding features and visualizations over time.

⚠️ Disclaimer: This project stores Strava data locally on your machine. It is the responsibility of each user to comply with Strava's API Agreement and their terms regarding data storage and usage. Please review Strava's policies before using this tool.

✨ Current features

Web Dashboard: Full-featured React frontend with FastAPI backend:
- 📅 Calendar: Monthly calendar with activity display, training session planning, and weekly reports
- 🏃 Activities: Browsable activity list with detail views, stream charts, and map visualization
- 🌍 World Footprint: Interactive Leaflet map with all your routes, filterable by sport and year
- ⚡ Year in Sport: Yearly stats with monthly charts, records, and sport breakdowns
- 👤 Profile: Athlete profile with HR zones, subscription status, and personal info
- 🌗 Dark/Light Mode: Full theme toggle with persistent preference
Activity Sync: Automatically sync and cache your Strava activities locally using Parquet files
Cool Visualizations: Generate visualizations including:
- ⚡ Thunderstorm Heatmap: Neon-style activity route visualization on dark backgrounds
- 🕐 Activity Clock: Polar scatter plot showing when you train (time vs distance)
- 🎛️ HUD Dashboard: Cyberpunk-style histograms for distance, heart rate, and pace
- 📈 Efficiency Factor: Track your aerobic efficiency (speed/HR) over time
- 🚀 Performance Frontier: Pareto frontier with Riegel's fatigue model fitting
- 📅 Weekly Report: Instagram Story-sized weekly training summary with HR zones, sports breakdown, and accumulated training time
- 🎯 Year in Sport: Instagram Story-sized summaries of your yearly training (main sport & totals)
- 🏆 Activity Plots: Neon-style individual activity visualization with elevation profile
Map Matching: Match GPS tracks to OpenStreetMap road networks using HMM-based matching:
- 🗺️ Street Coverage Map: Neon-glow visualization of all streets you've traversed in a city
- 📍 Activity Match Plot: Per-activity visualization showing GPS track, matched OSM edges, and snap points
- 📊 Coverage Stats: Track how many km of a city's street network you've covered
Analytics: WIP
GeoJSON Export: Export your activities as GeoJSON for use in mapping applications such as QGIS
Telegram Bot: Automated scheduled delivery of weekly and monthly reports to your Telegram chat
Smart Caching: Efficient local caching with incremental sync support to avoid redundant API calls

📋 Prerequisites

Python 3.12+
A Strava FREE account with API access
Strava API credentials (Client ID and Client Secret)

🔧 Installation

Using Poetry (Recommended)

# Clone the repository
git clone https://github.com/rsanchezmo/strava-intelligence.git
cd strava-intelligence

# Install dependencies with Poetry
poetry install

# Activate the virtual environment
poetry env activate

Using pip

# Clone the repository
git clone https://github.com/rsanchezmo/strava-intelligence.git
cd strava-intelligence

# Create a virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install the package
pip install -e .

🔑 Strava API Setup

Go to Strava API Settings
Create a new application to get your Client ID and Client Secret
Create a .env file in the project root:

STRAVA_CLIENT_ID=your_client_id
STRAVA_CLIENT_SECRET=your_client_secret

On first run, the app will open a browser for OAuth authorization. Follow the prompts to grant access.

🤖 Telegram Bot Setup (Optional)

You can optionally set up a Telegram bot to receive automated weekly reports (Sundays at 21:00) and monthly Year in Sport summaries (last day of month at 21:00).

Create a Telegram bot via @BotFather and get your bot token
Get your Telegram chat ID (send a message to your bot, then visit https://api.telegram.org/bot<YourBOTToken>/getUpdates)
Add these to your .env file:

TELEGRAM_BOT_TOKEN=your_bot_token
TELEGRAM_CHAT_ID=your_chat_id

Run the bot:

python telegram_bot.py

The bot supports manual commands:

/weekly - Generate and send current week's report
/monthly - Generate and send current year's report

🌐 Web Dashboard

Run the full web app (FastAPI backend + React frontend):

# Install dependencies
poetry install
cd frontend && npm install && cd ..

# Run both backend and frontend in development mode
python run_dev.py

The app will be available at http://localhost:5173. The backend API runs on http://localhost:8000.

🚀 Quick Start (Python API)

from strava.strava_intelligence import StravaIntelligence
from pathlib import Path

# Initialize (auto-syncs activities if cache is older than 12 hours)
strava = StravaIntelligence(workdir=Path("./strava_intelligence_workdir"))

# Generate a thunderstorm heatmap for your runs in Amsterdam
strava.strava_visualizer.thunderstorm_heatmap(
    sport_types=['Run'],
    location="amsterdam",
    radius_km=20.0,
    add_basemap=False
)

# Create an activity clock visualization
strava.strava_visualizer.activity_clock(sport_types=['Run'])

# Generate a HUD-style dashboard
strava.strava_visualizer.hud_dashboard(sport_types=['Run'])

# Plot efficiency factor trend
strava.strava_visualizer.plot_efficiency_factor(sport_types=['Run'])

# Plot performance frontier with fatigue model
strava.strava_visualizer.plot_performance_frontier(sport_types=['Run'])

# Generate Year in Sport summary (Instagram Story format)
strava.get_year_in_sport(year=2025, main_sport="Run", neon_color="#fc0101")

# Generate Year in Sport with comparison to previous year
strava.get_year_in_sport(
    year=2025, 
    main_sport="Run", 
    neon_color="#fc0101",
    comparison_year=2024,
    comparison_neon_color="#00aaff"
)

# Generate Weekly Report (Instagram Story format)
strava.get_weekly_report(week_start_date="2026-01-12", neon_color="#fc0101")

# Export activities as GeoJSON
strava.save_geojson_activities()

# --- Map Matching & Street Coverage ---
from strava.strava_map_matching import StravaMapMatcher
from strava.strava_utils import get_activities_as_gdf_from_streams

# Initialize the map matcher for a city
map_matcher = StravaMapMatcher(
    city_name="Amsterdam, Netherlands",
    workdir=Path("./strava_intelligence_workdir"),
    force_reload=False,
)

# Build a GeoDataFrame from high-res GPS streams
activities_gdf = get_activities_as_gdf_from_streams(
    strava.strava_activities_cache.activities
)

# Match all activities to the OSM road network
matched_gdf, match_details = map_matcher.match(activities_gdf)

# Plot individual activity match results
for activity_id, result in match_details.items():
    result.plot(save_path=f"map_match_{activity_id}.png")

# Generate a city-wide street coverage map
map_matcher.plot_coverage(match_details, save_path="amsterdam_coverage.png")

📊 Visualizations

Thunderstorm Heatmap

A stunning neon visualization of your activity routes on a dark canvas. Perfect for showcasing your training coverage in a specific area.

Thunderstorm Heatmap	Activity Clock

Neon-style route visualization on dark backgrounds	Polar plot showing training patterns by time of day

HUD Dashboard & Analytics

HUD Dashboard	Efficiency Factor	Performance Frontier

Distance, HR & Pace distributions	Aerobic efficiency over time	Best performances with Riegel's model

Weekly Report & Bubble Map

Weekly Report	Bubble Map

Instagram Story-sized weekly summary with HR zones, sport breakdowns, and training progression	Geographic bubble visualization of activity locations

Year in Sport

Generate Instagram Story-sized (9:16) summaries of your yearly training with optional year comparison.

Main Sport	All Sports	Activity Plot

Stats, monthly chart & personal bests	Aggregated stats across all sports	Route map with elevation profile

Year Comparison — Run	Year Comparison — Totals

Side-by-side stats with grouped bar charts	Cross-sport comparison with highlighted differences

Map Matching & Street Coverage

Match your Strava activities to the OpenStreetMap road network using HMM-based map matching.

Street Coverage Map	Activity Match Plot

Traversed streets glow in neon against the dim untraversed network	GPS track (red), matched OSM edges (blue), snap connections (white)

QGIS GeoJSON Export

Export your activities as GeoJSON for advanced spatial analysis in QGIS.

All Activities	Activity Info

🏗️ Project Structure

strava-intelligence/
├── main.py                    # Example usage (Python API)
├── run_dev.py                 # Dev server launcher (backend + frontend)
├── pyproject.toml             # Poetry configuration
├── README.md
├── backend/                   # FastAPI backend
│   ├── app.py                 # FastAPI application
│   ├── config.py              # Settings
│   ├── dependencies.py        # Dependency injection
│   ├── db.py                  # SQLite for calendar sessions
│   └── routers/               # API route handlers
│       ├── activities.py
│       ├── athlete.py
│       ├── calendar.py
│       ├── exports.py
│       ├── stats.py
│       └── sync.py
├── frontend/                  # React + Vite frontend
│   ├── src/
│   │   ├── App.tsx
│   │   ├── api/               # API client & React Query hooks
│   │   ├── components/        # Shared components (MapView, charts, layout)
│   │   ├── hooks/             # Custom hooks (useTheme)
│   │   └── pages/             # Page components
│   └── ...
└── strava/                    # Core Python library
    ├── constants.py           # CRS constants
    ├── strava_activities_cache.py  # Activity caching logic
    ├── strava_analytics.py    # Analytics calculations
    ├── strava_endpoint.py     # Strava API client
    ├── strava_intelligence.py # Main orchestrator class
    ├── strava_map_matching.py # OSM map matching & coverage
    ├── strava_user_cache.py   # User data caching
    ├── strava_utils.py        # Utility functions
    └── strava_visualizer.py   # Visualization generators

📝 API Reference