spotifyapi package

Submodules

spotifyapi.api_constants module

Module storing constants for the Spotify API.

spotifyapi.api_constants.DATA_DIR

Path to directory to store saved access token

spotifyapi.api_constants.ARTISTS_ENDPOINT

Get Spotify catalog information for a single artist identified by their unique Spotify ID.

spotifyapi.api_constants.AUDIO_FEATURES_ENDPOINT

Get audio feature information for a single track identified by its unique Spotify ID.

spotifyapi.get_access_token module

spotifyapi.get_access_token.get_access_token(client_id: str, client_secret: str, timeout: float = 60, retries: int = 3) → str[source]

Gets a valid access token from the Spotify API.

Provided a client ID and client secret, this function will get a valid access token from the Spotify API. If a token file exists, it will check if the token is expired. If the token is expired, it will get a new token and overwrite the existing token file. If the token file does not exist, it will get a new token and write it to a new token file.

Parameters:

  • client_id – A user’s Spotify client ID (from the Spotify Developer Dashboard).

  • client_secret – A user’s Spotify client secret (from the Spotify Developer Dashboard).

  • timeout – The number of seconds to wait for the server to send data before giving up and retrying.

  • retries – The maximum number of retries to attempt if the request fails before throwing an exception.

Returns:

A valid access token from the Spotify API as a string.

Raises:

  • TimeoutError – If the request times out.

  • RequestException – If the request fails (the status code is not 200).

Example

>>> access_token = spotifyapi.get_access_token(client_id, client_secret, timeout=60, retries=3)
spotifyapi.get_access_token.get_new_access_token(client_id, client_secret, timeout=60, retries=3) → str[source]

Utily function called by get_access_token() to get a new access token without checking for an existing token file.

This is a utility function. Users should instead use get_access_token(). Provided a client ID and client secret, this function will query the Spotify API for a new access token. If the request is successful, it will calculate the expire time and return the response data. If the request fails, it will print an error and return None. If the request times out, it will retry the request up to the number of retries specified. If the request is successful, but the status code is not 200, it will print an error and return None.

Parameters:

  • client_id – A user’s Spotify client ID (from the Spotify Developer Dashboard).

  • client_secret – A user’s Spotify client secret (from the Spotify Developer Dashboard).

  • timeout – The number of seconds to wait for the server to send data before giving up and retrying.

  • retries – The maximum number of retries to attempt if the request fails before throwing an exception.

Returns:

A valid access token from the Spotify API as a string.

Raises:

  • TimeoutError – If the request times out.

  • RequestException – If the request fails (the status code is not 200).

Example

>>> access_token = spotifyapi.get_new_access_token(client_id, client_secret, timeout=60, retries=3)

spotifyapi.get_artist_albums module

spotifyapi.get_artist_albums.get_artist_albums(artist_id: str, access_token: str, limit: int = 10) → list[source]

Retrieve a list of an artist’s albums and the albums’ data for a given artist ID.

Given an artist ID and an access token, this function will query the Spotify API for a list of the artist’s albums and the albums’ data. If the request is successful, it will return the response data. If the request fails, it will print an error and return None. If the request is successful, but the status code is not 200, it will print an error and return None.

Parameters:

  • artist_id – A Spotify artist ID.

  • access_token – A valid access token from the Spotify API.

  • limit – The maximum number of albums to return.

Returns:

A list of album data from the Spotify API.

Raises:

  • TimeoutError – If the request times out.

  • RequestException – If the request fails (the status code is not 200).

Example

>>> artist_id = '4PTG3Z6ehGkBFwjybzWkR8'
>>> access_token = spotifyapi.get_access_token(client_id, client_secret, timeout=60, retries=3)
>>> album_data = spotifyapi.get_artist_albums(artist_id, access_token, limit=10)

spotifyapi.get_artist_top_tracks module

spotifyapi.get_artist_top_tracks.get_artist_top_tracks(artist_id: str, access_token: str, market='US') → list[source]

Retrieve top tracks for an artist from the Spotify API.

Tiven an artist ID, this function will query the Spotify API for the artist’s top tracks. If the request is successful, it will return the list of top tracks. If the request times out, it will print an error and return None. If the request fails, it will print an error and return None.

Parameters:

  • artist_id – A Spotify artist ID.

  • access_token – A valid access token from the Spotify API.

  • market – An ISO 3166-1 alpha-2 country code for which the top tracks are determined.

Returns:

A list of top tracks for the specified artist.

Raises:

  • TimeoutError – If the request times out.

  • RequestException – If the request fails (the status code is not 200).

Example

>>> artist_id = '4PTG3Z6ehGkBFwjybzWkR8'
>>> access_token = spotifyapi.get_access_token(client_id, client_secret, timeout=60, retries=3)
>>> top_tracks = spotifyapi.get_artist_top_tracks(artist_id, access_token, market='US)

spotifyapi.get_artists module

spotifyapi.get_artists.get_artists(artist_ids: str | list[str], access_token: str) → list[source]

Retrieve artist data for one or multiple artists from the Spotify API.

Parameters:

  • artist_ids (str or list) – A single artist ID as a string or a list of artist IDs.

  • access_token (str) – Spotify access token for authentication.

Returns:

Artist data for the specified artist(s).

Return type:

dict

Example

>>> artist_ids = '0TnOYISbd1XYRBk9myaseg'
>>> access_token = 'your_spotify_access_token'
>>> artist_info = spotifyapi.get_artists(artist_ids, access_token)

spotifyapi.get_tracks_audio_features module

spotifyapi.get_tracks_audio_features.get_tracks_audio_features(track_ids: str | list[str], access_token: str) → list[source]

Retrieve audio features for one or multiple tracks from the Spotify API.

Parameters:

  • track_ids (str or list) – A single track ID as a string or a list of track IDs.

  • access_token (str) – Spotify access token for authentication.

Returns:

Audio features data for the specified track(s).

Return type:

dict

Example

>>> track_ids = '4cOdK2wGLETKBW3PvgPWqT'
>>> access_token = 'your_spotify_access_token'
>>> audio_features = spotifyapi.get_tracks_audio_features(track_ids, access_token)

spotifyapi.query_spotify_api module

spotifyapi.query_spotify_api.query_spotify(endpoint: str, access_token: str, timeout: float = 60, retries: int = 3) → dict[source]

Query the Spotify API at the specified endpoint.

Parameters:

  • endpoint (str) – The API endpoint to query.

  • access_token (str) – Spotify access token for authentication.

  • timeout (int, optional) – Maximum time (in seconds) to wait for the request to complete. Defaults to 60.

  • retries (int, optional) – Number of retry attempts in case of failure. Defaults to 3.

Returns:

The JSON response from the Spotify API if the request is successful,

otherwise returns None.

Return type:

dict or None

Example

>>> endpoint = 'https://api.spotify.com/v1/tracks/3Hvu1pq89dGspIjqBBMIsU'
>>> access_token = 'your_spotify_access_token'
>>> track_info = spotifyapi.query_spotify(endpoint, access_token)

spotifyapi.clean_data module

spotifyapi.clean_data.clean_genres(df, prioritized_genres)[source]

Filter the ‘genres’ column of a DataFrame to keep only prioritized genres or genres containing the listed genres Order Matters, if there is Indie Rock, and the list is (‘Indie’, ‘Pop’, ‘Rock’), ‘Indie’ will be kept.

Parameters:

  • df (DataFrame) – Input DataFrame.

  • prioritized_genres (list) – List of prioritized genres.

Returns:

Filtered DataFrame with only prioritized genres.

Return type:

DataFrame

spotifyapi.clean_data.join_tables(track_arg, artist_arg, audio_feature_arg, use_dfs=True)[source]

Join three tables based on common columns.

Parameters:

  • track_arg (str or DataFrame) – File path or DataFrame for the track data.

  • artist_arg (str or DataFrame) – File path or DataFrame for the artist data.

  • audio_feature_arg (str or DataFrame) – File path or DataFrame for the audio feature data.

  • use_dfs (bool, optional) – If True, treat the arguments as DataFrame objects. If False, treat the arguments as file paths and read them using pandas. Default is True.

Returns:

Merged data.

Return type:

DataFrame

Example

>>> result_df_objects = spotifyapi.join_tables(track_df, artist_df, audio_feature_df, use_dfs=True)

Module contents