spotify-connector

KO | EN

gitlite — search

#javascript #python #react #ai #typescript #go #rust #docker #macos #nodejs #java #awesome-list #mcp #open-source

spotify-connector

(★ 33)

Inofficial Connector for Spotify's Podcast Data

spotify-connector Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Spotify Connector

[![Docs](https://readthedocs.org/projects/spotify-connector/badge?version=latest)](https://spotify-connector.readthedocs.io)

[![OpenPodcast Banner](https://raw.githubusercontent.com/openpodcast/banner/main/openpodcast-banner.png)](https://openpodcast.app/)

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](https://github.com/openpodcast/web-extension) for that
or [take a look at the code](https://github.com/openpodcast/web-extension/blob/7ce0865d22bea34fcfc53eec06b25cd076aa8034/src/openpodcast.js)
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

```python
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:

```sh
make dev
```

To run the script with verbose logging:

```sh
export LOGURU_LEVEL=TRACE
make dev
```

## Development

We use [uv] for virtualenv and dependency management. With uv [installed][uv-install]:

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

```sh
uv sync --all-extras --group dev
```

Or simply:

```sh
make install
```

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

```sh
cp .env.example .env
```

3. Run the script in the virtual environment:

```sh
uv run spotifyconnector
```

To add a new runtime dependency:

```sh
uv add $package
```

To add a new development-only dependency:

```sh
uv add --group dev $package
```

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

```sh
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.

[uv]: https://docs.astral.sh/uv/
[uv-install]: https://docs.astral.sh/uv/getting-started/installation/
[wdr-okr]: https://github.com/wdr-data/wdr-okr

spotify-connector

spotify-connector Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

spotify-connector

spotify-connector Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README