🏃 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

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
- 🎯 Year in Sport: Instagram Story-sized summaries of your yearly training (main sport & totals)
- 🏆 Activity Plots: Neon-style individual activity visualization with elevation profile
Analytics: WIP
GeoJSON Export: Export your activities as GeoJSON for use in mapping applications sycg as QGIS
Smart Caching: Efficient local caching with incremental sync supportm 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.

🚀 Quick Start

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

# Export activities as GeoJSON
strava.save_geojson_activities()

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

Activity Clock

A polar plot showing the distribution of your activities by time of day and distance. Discover your training patterns at a glance.

HUD Dashboard

Cyberpunk-inspired histograms displaying the distribution of:

Distance (km)
Heart Rate (bpm)
Pace (min/km)

Efficiency Factor

Track your aerobic efficiency over time with rolling averages and variance bands. Identify peak performance periods.

Performance Frontier

Visualize your best performances across different distances with Riegel's power-law fatigue model fitting.

Bubble Map

Geographic bubble visualization showing your activity locations with size proportional to distance or count. Great for visualizing where you train most.

Year in Sport

Generate Instagram Story-sized (9:16) summaries of your yearly training. Includes stats for your main sport and totals across all activities, plus individual activity plots for your personal bests. Now with year comparison feature to compare your progress against previous years!

Main Sport Summary - Shows total activities, kilometers, hours, elevation, monthly distance chart, and personal bests (longest distance, longest time, fastest pace).

All Sports Summary - Aggregated stats across all sports with breakdown by sport type.

Year Comparison - Compare your current year against a previous year with side-by-side stats, grouped bar charts, and highlighted differences.

Activity Plot - Individual activity visualization with route map and elevation profile.

QGIS GeoJSON Export

Easily export your Strava activities as GeoJSON files for advanced mapping and spatial analysis in GIS software like QGIS.

🏗️ Project Structure

strava-intelligence/
├── main.py                    # Example usage
├── pyproject.toml             # Poetry configuration
├── README.md
└── strava/
    ├── 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_user_cache.py   # User data caching
    ├── strava_utils.py        # Utility functions
    └── strava_visualizer.py   # Visualization generators

📝 API Reference