strava-heatmap-proxy

This software allows streaming high resolution Strava Global Heatmap tiles with clients like QGIS, QMapShack, JOSM and many others without requiring them to be able to handle the Strava specific authentication and session management.

To do so, you need the following two pieces:

1. The strava-cookie-exporter browser extension to export the necessary cookies as json file
2. The strava-heatmap-proxy server which adds the necessary cookies to your requests before redirecting them to Strava

Note: Previous versions of this repository were able to login to Strava automatically when running the proxy server. Due to recent changes on Strava side this is not possible anymore and we need to extract (at least) a valid session identifier via the browser extension. The proxy will then automatically refresh CloudFront tokens in case they have expired.

This proxy can be run locally on your computer.
Or can be deployed to Google Cloud Run, find the Details in the uber-next Section.

Local Proxy: Getting started

Build and Install

With git, golang and make available on your system, the following steps are sufficient to build and install strava-heatmap-proxy to the given path:

git clone https://github.com/limex/strava-heatmap-proxy
cd strava-heatmap-proxy
make install

creates a folder /build with the executable.

Using the browser extension

You can install the strava-cookie-exporter extension for Firefox from the Mozilla add-on store here.

You can install the strava-cookie-exporter extension for Chrome from the Chrome Web store here.

With this extension installed, you can:

• Use your browser to login and navigate to the Strava Global Heatmap
• Use the strava-cookie-exporter extension to export the relevant cookies as json file

The exported json file is needed for running strava-heatmap-proxy.

Using the proxy server

Running the tool strava-heatmap-proxy from your terminal will set up a local proxy server for https://content-a.strava.com/.

Available options:

• -cookies <file>: Path to the cookies JSON file (default: ~/.config/strava-heatmap-proxy/strava-cookies.json)
• -port <port>: Local proxy port (default: 8080)
• -target <url>: Target Strava heatmap URL (default: https://content-a.strava.com/)
• -apikeys <file>: (optional) Path to API keys configuration file (default: ~/.config/strava-heatmap-proxy/api-keys.json)

API Key Authentication (Optional)

You can optionally secure your proxy with API key authentication. Obviously, this doesn't make that much sense when running the proxy on your local machine when you're the only user, but there are use cases where you want to run that on a server or on a desktop that is shared among a network. Or deploy the Proxy to i.e. Google Cloud Run as described below.

Create an API keys configuration file with minimum one key :

{
  "keys": [
    "your-secret-api-key-1",
    "your-secret-api-key-2",
    "another-api-key"
  ]
}

When a api-keys.json key is present, all requests must include a valid key parameter:

http://localhost:8080/identified/globalheat/all/bluered/10/512/384.png?v=19&key=your-secret-api-key-1

If no API keys file is found or the file is empty, the proxy runs without authentication (previous behavior).

Every request to http://localhost:8080/ will then be extended with session cookies before being forwarded to Strava. You can configure different target URLs or port numbers via --target or --port as well.

By default, the necessary cookies are expected to be found in the file ${HOME}/.config/strava-heatmap-proxy/strava-cookies.json (should be manually created with the strava-cookie-exporter extension). You can configure different locations of that file via --cookies as well.

The CloudFront cookies have an expiration period of 24 hours, but you don't need to recreate the strava-cookies.json file all the time because strava-heatmap-proxy can automatically refresh expired cookies as long as the session is valid (the exact duration of that is unkown right now).

Sadly the Strava Cookie needs manual update every weeks/month. When the proxy stops working, get a fresh json from the browser extension to the build folder (for the cloud deployment) or to ~/.config/strava-heatmap-proxy/strava-cookies.json (if you use locoal deployment)

For cloud run:
./deploy.sh.
This will: Rebuild the Docker image with fresh cookies baked in Deploy the new image to Cloud Run The proxy will start with fresh cookies and auto-maintain them

In GIS, QMapShack

To use this with your GIS software of choice, just define a simple TMS layer like shown below that fetches high resolution heatmap tiles:

<TMS>
  <Title>StravaGlobalHeatmap</Title>
  <MinZoomLevel>5</MinZoomLevel>
  <MaxZoomLevel>16</MaxZoomLevel>
  <Layer idx="0">
    <ServerUrl>http://localhost:8080/identified/globalheat/all/bluered/%1/%2/%3.png?v=19</ServerUrl>
  </Layer>
</TMS>

This is how the result might look like in QMapShack:

in bikerouter.de

Add http://localhost:8080/identified/globalheat/all/bluered/{z}/{x}/{y}.png?v=19 in a Custom Layer

other Sports ...

http://localhost:8080/identified/globalheat/sport_Hike/hot/{z}/{x}/{y}.png?v=19
http://localhost:8080/identified/globalheat/sport_Ride/hot/{z}/{x}/{y}.png?v=19
http://localhost:8080/identified/globalheat/sport_MountainBikeRide/hot/{z}/{x}/{y}.png?v=19
http://localhost:8080/identified/globalheat/sport_Run/hot/{z}/{x}/{y}.png?v=19
http://localhost:8080/identified/globalheat/sport_GravelRide/hot/{z}/{x}/{y}.png?v=19
http://localhost:8080/identified/globalheat/ride/hot/15/{z}/{x}/{y}.png?v=19
http://localhost:8080/identified/globalheat/water/hot/15/{z}/{x}/{y}.png?v=19
http://localhost:8080/identified/globalheat/sport_BackcountrySki/{z}/{x}/{y}.png?v=19
http://localhost:8080/identified/globalheat/sport_NordicSki/hot/{z}/{x}/{y}.png?v=19

More Examples actual tiles

adopt the Z/X/Y part (/15/17793/11515) accordingly to your need.

http://localhost:8080/identified/globalheat/sport_Hike/hot/15/17793/11515.png?v=19
http://localhost:8080/identified/globalheat/sport_Ride/hot/15/17793/11514.png?v=19
http://localhost:8080/identified/globalheat/sport_MountainBikeRide/hot/15/17793/11515.png?v=19
http://localhost:8080/identified/globalheat/sport_Run/hot/15/17793/11515.png?v=19
http://localhost:8080/identified/globalheat/sport_GravelRide/hot/15/17794/11514.png?v=19
http://localhost:8080/identified/globalheat/ride/hot/15/17794/11514.png?v=19
http://localhost:8080/identified/globalheat/water/hot/15/17792/11514.png?v=19
http://localhost:8080/identified/globalheat/sport_BackcountrySki/hot/11/1112/719.png?v=19
http://localhost:8080/identified/globalheat/sport_NordicSki/hot/9/277/179.png?v=19

Running in Google Cloud Run

See DEPLOYMENT.md for detailed deployment instructions on Google Cloud Run.

Changes after forking

• Added Option to deploy to Google Cloud run
• Added license keys feature
• Fixed Issue is Browser Extension, that prevented usage in Chrome.
• Update to Go 1.25
• Persist refreshed CloudFront cookies back to strava-cookies.json (atomic write via temp file + rename) so they survive proxy restarts
• Detect 403 responses from Strava CDN and immediately force a cookie refresh using a ModifyResponse hook on the reverse proxy
• Guard concurrent refresh calls with an atomic bool to prevent redundant simultaneous HEAD requests to Strava on cookie expiry
• Add /health endpoint returning cookie expiry time; triggers a proactive background refresh when cookies are within 4h of expiry
• Set up Cloud Scheduler job (europe-west3) to hit /health every 20h, refreshing cookies before Strava's 24h expiry window

References

1. Original repo of Patrick Ziegler https://github.com/patrickziegler/strava-heatmap-proxy
2. Discussion in bertt/wmts#2 revealed the meaning of CloudFront-* tokens
3. https://github.com/erik/strava-heatmap-proxy was following a similar approach but is designed to be a Cloudflare worker

License

This project is licensed under the GPL - see the LICENSE file for details