Welcome to Spotify Analyzer

You can use this tool to retrieve data about your listening history on Spotify, export them in a .csv or .xlsx file and do some lovely analysis.

You can download the binary files (only for Windows) in the Releases page.

This tools uses the official Spotify Web API and in order to access them you have to:

1. Go to the Dashboard page at the Spotify Developer website and, if necessary, log in.

2. Click on "Create an App"

3. Choose a name for the app and click on "Create"

4. Now you have your personal App, congrats. Click on "EDIT SETTINGS" and in the "Redirect URIs" field enter this string:

   http://localhost:8888/callback/

5. Click on "SAVE".

6. Copy the Client ID and the Secret ID

7. Open the Spotify Data Retriever app and paste them in the appropriate forms

8. Choose the options you like and press "START"

9. Profit(?)

Running from source

Python 3.9 or newer. One command, Linux/macOS:

./run.sh

The first run creates the virtual environment and installs the dependencies; every later run goes straight to the app — no activation needed.

With uv installed there is an even shorter zero-setup path (no manual venv at all):

uv run main.py

On Windows (or without uv), the classic way still works:

python -m venv .venv
.venv\Scripts\pip install -r requirements.txt
.venv\Scripts\python main.py

Exports (.csv/.xlsx), the Spotify token caches and your credentials (.env) all live either next to the app or in ~/spotify-analyzer-data; none of them are committed (see .gitignore).

Offline tests

The analysis and export logic is covered by a headless test suite that stubs the Spotify API and the GUI:

python tests/test_core.py

Data quality icons created by juicy_fish - Flaticon