Spotify Connector

This is a simple library for connecting to the unofficial Spotify podcast API.
It can be used to export data from your dashboard at https://podcasters.spotify.com/home.

Supported Data

• List of episodes
• Starts and streams
• Listeners
• Followers
• Gender
• Age
• Country
• Episode performance

Credentials

Before you can use the library, you must extract your Spotify credentials from the dashboard; they are not exposed through your Spotify settings.

You can use our web extension for that or take a look at the code to see how to do it manually.

You need three values:

• sp_dc: Can be found in the Spotify cookies once you're logged in. It's a long string with around 160 characters.
• sp_key: Can also be found in the Spotify cookies once you're logged in. It's a UUID (36 characters).
• client_id: This is a static value and stays the same for everyone. It is 05a1371ee5194c27860b3ff3ff3979d2. Spotify might change it in the future, so if you run into issues, please check your network requests while logged in to find the new value.

Installation

pip install spotifyconnector

Usage as a library

from spotifyconnector import SpotifyConnector

# Set up the connector
connector = SpotifyConnector(
    base_url="https://generic.wg.spotify.com/podcasters/v0123"
    client_id="05a1371ee5194c27860b3ff3ff3979d2", # login to spotify and monitor connection to get this id
    podcast_id="your_spotify_podcast_id",
    sp_dc="xxxxxxxxxxxxxxxxxx...xxx", # can be found in cookies after logged in (long string)
    sp_key="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" # can be found in cookies after logged in
)

# Get podcast metadata
connector.metadata()

# Get the list of listeners of a podcast
listeners = connector.listeners()

# Get the aggregated listeners of a podcast (by age, country, gender)
aggregate = connector.aggregate()

# Iterate over all episodes (supports pagination)
for episode in connector.episodes():
    # Do something with episode
    pass

# Get the performance of an episode
performance = connector.performance("episode_id")

# ...

See __main.py__ for all endpoints.

Local Testing

You can run the script locally to test it:

make dev

To run the script with verbose logging:

export LOGURU_LEVEL=TRACE
make dev

Development

We use uv for virtualenv and dependency management. With uv installed:

1. Install your locally checked-out code in editable mode, including all runtime, optional, and dev dependencies into a .venv/ virtual environment:

uv sync --all-extras --group dev

Or simply:

make install

2. Create an environment file and fill in the required values:

cp .env.example .env

3. Run the script in the virtual environment:

uv run spotifyconnector

To add a new runtime dependency:

uv add $package

To add a new development-only dependency:

uv add --group dev $package

To build the package locally (sdist + wheel into dist/):

uv build

Releasing

Releases are published to PyPI automatically by GitHub Actions when a new GitHub release is created.

1. Bump the version field in pyproject.toml.
2. Commit the bump and open a PR; merge it once CI is green.
3. Create a new GitHub release with a tag like v0.8.3 matching the version in pyproject.toml. The Deploy workflow will build with uv build and publish via twine using the PYPI_API_TOKEN secret.

Credits

This was inspired by the code at wdr-okr, extended and released to PyPi.