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.

Installation¶

pip install spotifyconnector

Usage as a library¶

from spotifyconnector import SpotifyConnector

# Set up the connector
connector = SpotifyConnector(
    client_id="your_client_id",
    client_secret="your_client_secret",
    redirect_uri="your_redirect_uri",
    refresh_token="your_refresh_token",
)

# 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 Pipenv for virtualenv and dev dependency management. With Pipenv installed:

Install your locally checked out code in development mode, including its dependencies, and all dev dependencies into a virtual environment:

pipenv sync --dev

Create an environment file and fill in the required values:

cp .env.example .env

Run the script in the virtual environment, which will automatically load your .env:

pipenv run spotifyconnector

To add a new dependency for use during the development of this library:

pipenv install --dev $package

To add a new dependency necessary for the correct operation of this library, add the package to the install_requires section of ./setup.py, then:

pipenv install

To publish the package:

python setup.py sdist bdist_wheel
twine upload dist/*

or

make publish

Credits¶

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

API¶

This package allows you to fetch data from the inofficial Spotify Podcast API. The API is not documented and may change at any time. Use at your own risk.

class spotifyconnector.SpotifyConnector(base_url, client_id, podcast_id, sp_dc, sp_key)[source]¶

Representation of the inofficial Spotify podcast API.

aggregate(start: date, end: date | None = None, episode=None) → dict[source]¶

Loads podcast aggregate data, which includes the number of starts and completions for each episode.

Args:

start (dt.date): Earliest date to request data for. end (Optional[dt.date], optional): Most recent date to request data for.

Defaults to None. Will be set to start if None.

episode (str): ID of the episode to request data for (optional).: If this is not provided, data for all episodes will be returned.

Returns:

dict: [aggregate]

catalog() → dict[source]¶

Loads podcast catalog data.

Returns:: dict: [catalog]

episodes(start: date, end: date | None = None, page: int = 1, size: int = 50, sort_by: str = 'releaseDate', sort_order: str = 'descending', filter_by: str = '') → dict[source]¶

Loads podcast episode data, which includes the number of starts and completions for each episode.

Returns an iterator over all episodes.

Args:

episode (str): ID of the episode to request data for. start (dt.date): Earliest date to request data for. end (Optional[dt.date], optional): Most recent date to request data for.

Defaults to None. Will be set to start if None.

page (int): Page number to request size (int): Number of results per page sort_by (str): Sort by field sort_order (str): Sort order filter_by (str): Filter by field

Returns:

(iterable): [episode]

followers(start: date, end: date | None = None) → dict[source]¶

Loads podcast follower data.

Args:: start (dt.date): Earliest date to request data for. end (Optional[dt.date], optional): Most recent date to request data for.

Defaults to None. Will be set to start if None.
Returns:: dict: [description]

listeners(start: date, end: date | None = None, episode=None) → dict[source]¶

Loads podcast listener data, which includes the number of listeners for each episode.

Args:

start (dt.date): Earliest date to request data for. end (Optional[dt.date], optional): Most recent date to request data for.

Defaults to None. Will be set to start if None.

episode (str): ID of the episode to request data for (optional).: If this is not provided, data for all episodes will be returned.

Returns:

dict: [description]

metadata(episode=None) → dict[source]¶

Loads metadata for podcast.

Args:

episode (str): ID of the episode to request data for (optional).: If this is not provided, data for all episodes will be returned.

Returns:

dict: Response data from API.

performance(episode: str) → dict[source]¶

Gets the episode performance data for a given episode.

Args:: episode (str): ID of the episode to request data for.
Returns:: dict: [performance]

streams(start: date, end: date | None = None, episode=None) → dict[source]¶

Loads podcast/episode stream data, which includes the number of starts and completions for each episode.

Args:

start (dt.date): Earliest date to request data for. end (Optional[dt.date], optional): Most recent date to request data for.

Defaults to None. Will be set to start if None.

episode (str): ID of the episode to request data for (optional).: If this is not provided, data for all episodes will be returned.

Returns:

dict: [description]

Spotify Connector¶