Spotipy

https://spotipy.readthedocs.io/en/master/
Admin
Spotipy is a lightweight Python library that provides full access to the Spotify Web API, enabling...
Tokens:29,159
Snippets:150
Trust Score:8.3
Update:6 months ago
Show doc for...
Tokens:
Raw
### Setup Development Environment

Source: https://spotipy.readthedocs.io/en/master/_sources/index.rst.txt

Commands to initialize a virtual environment, install dependencies, and execute the test suite.

```bash
$ virtualenv --python=python3.12 env
(env) $ pip install --user -e .
(env) $ python -m unittest discover -v tests
```

--------------------------------

### Setup Development Environment and Run Tests

Source: https://spotipy.readthedocs.io/en/master/index.html

Commands to initialize a virtual environment, install dependencies in editable mode, and execute the test suite.

```bash
$ virtualenv –python=python3.12 env (env) $ pip install –user -e . (env) $ python -m unittest discover -v tests
```

--------------------------------

### Install Spotipy

Source: https://spotipy.readthedocs.io/en/master/_sources/index.rst.txt

Install or upgrade Spotipy using pip.

```bash
pip install spotipy --upgrade
```

--------------------------------

### GET /available_markets

Source: https://spotipy.readthedocs.io/en/master/index.html

Get the list of markets where Spotify is available.

```APIDOC
## GET /available_markets

### Description
Get the list of markets where Spotify is available. Returns a list of the countries in which Spotify is available, identified by their ISO 3166-1 alpha-2 country code.

### Method
GET

### Endpoint
/available_markets
```

--------------------------------

### GET /categories

Source: https://spotipy.readthedocs.io/en/master/index.html

Get a list of categories.

```APIDOC
## GET /categories

### Description
Get a list of categories.

### Method
GET

### Endpoint
/categories

### Parameters
#### Query Parameters
- **country** (string) - Optional - An ISO 3166-1 alpha-2 country code.
- **locale** (string) - Optional - The desired language, consisting of an ISO 639-1 alpha-2 language code and an ISO 3166-1 alpha-2 country code, joined by an underscore.
- **limit** (integer) - Optional - The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50
- **offset** (integer) - Optional - The index of the first item to return. Default: 0.
```

--------------------------------

### PUT /me/player/play

Source: https://spotipy.readthedocs.io/en/master/index.html

Starts or resumes the user's playback.

```APIDOC
## PUT /me/player/play

### Description
Start or resume user’s playback.

### Method
PUT

### Parameters
#### Request Body
- **device_id** (string) - Optional - Device target for playback.
- **context_uri** (string) - Optional - Spotify context uri to play.
- **uris** (list) - Optional - Spotify track uris.
- **offset** (object) - Optional - Offset into context by index or track.
- **position_ms** (integer) - Optional - Indicates from what position to start playback.
```

--------------------------------

### GET /user

Source: https://spotipy.readthedocs.io/en/master/index.html

Gets basic profile information about a Spotify user.

```APIDOC
## GET /user

### Description
Gets basic profile information about a Spotify User.

### Parameters
#### Path Parameters
- **user** (string) - Required - The id of the user
```

--------------------------------

### Initialize Spotipy Client and Fetch Data

Source: https://spotipy.readthedocs.io/en/master/index.html

Demonstrates basic usage of the Spotipy client to fetch artist and user information. Ensure spotipy is installed and authenticated if necessary for private data.

```python
import spotipy

urn = 'spotify:artist:3jOstUTkEu2JkjvRdBA5Gu'
sp = spotipy.Spotify()

artist = sp.artist(urn)
print(artist)

user = sp.user('plamere')
print(user)

```

--------------------------------

### Authorization Code Flow Quick Start

Source: https://spotipy.readthedocs.io/en/master/index.html

Demonstrates how to authenticate using the Authorization Code Flow with SpotifyOAuth and retrieve saved tracks. Requires setting up environment variables for credentials.

```python
import spotipy
from spotipy.oauth2 import SpotifyOAuth

scope = "user-library-read"

sp = spotipy.Spotify(auth_manager=SpotifyOAuth(scope=scope))

results = sp.current_user_saved_tracks()
for idx, item in enumerate(results['items']):
    track = item['track']
    print(idx, track['artists'][0]['name'], " – ", track['name'])

```

--------------------------------

### GET /me

Source: https://spotipy.readthedocs.io/en/master/index.html

Get detailed profile information about the current user.

```APIDOC
## GET /me

### Description
Get detailed profile information about the current user.

### Method
GET

### Endpoint
/me
```

--------------------------------

### Get User's Queue

Source: https://spotipy.readthedocs.io/en/master/index.html

Gets the current user’s playback queue.

```APIDOC
## GET /player/queue

### Description
Gets the current user’s queue.

### Method
GET

### Endpoint
/player/queue
```

--------------------------------

### Get Recommendations

Source: https://spotipy.readthedocs.io/en/master/index.html

Get a list of recommended tracks for one to five seeds. At least one of seed_artists, seed_tracks and seed_genres are needed. This endpoint has been removed by Spotify and is no longer available.

```APIDOC
## GET /recommendations

### Description
Get a list of recommended tracks for one to five seeds. (at least one of seed_artists, seed_tracks and seed_genres are needed)
This endpoint has been removed by Spotify and is no longer available.

### Method
GET

### Endpoint
/recommendations

### Parameters
#### Query Parameters
- **seed_artists** (array of strings) - Optional - A list of artist IDs, URIs or URLs.
- **seed_tracks** (array of strings) - Optional - A list of track IDs, URIs or URLs.
- **seed_genres** (array of strings) - Optional - A list of genre names. Available genres for recommendation.
- **limit** (integer) - Optional - The maximum number of tracks to return (default: 20).
- **country** (string) - Optional - An ISO 3166-1 alpha-2 country code.
- **kwargs** - Additional keyword arguments.
```

--------------------------------

### GET /browse/new-releases

Source: https://spotipy.readthedocs.io/en/master/index.html

Get a list of new album releases featured in Spotify.

```APIDOC
## GET /browse/new-releases

### Description
Get a list of new album releases featured in Spotify.

### Method
GET

### Endpoint
/browse/new-releases

### Parameters
#### Query Parameters
- **country** (string) - Optional - An ISO 3166-1 alpha-2 country code.
- **limit** (integer) - Optional - The maximum number of items to return. Default: 20.
- **offset** (integer) - Optional - The index of the first item to return. Default: 0.
```

--------------------------------

### Get Playlist Items

Source: https://spotipy.readthedocs.io/en/master/index.html

Get full details of the tracks and episodes of a playlist.

```APIDOC
## GET /playlists/{playlist_id}/tracks

### Description
Get full details of the tracks and episodes of a playlist.

### Method
GET

### Endpoint
/playlists/{playlist_id}/tracks

### Parameters
#### Path Parameters
- **playlist_id** (string) - Required - The playlist ID, URI or URL.

#### Query Parameters
- **fields** (string) - Optional - Which fields to return.
- **limit** (integer) - Optional - The maximum number of tracks to return (default: 50).
- **offset** (integer) - Optional - The index of the first track to return (default: 0).
- **market** (string) - Optional - An ISO 3166-1 alpha-2 country code.
- **additional_types** (array of strings) - Optional - List of item types to return (valid types are: track and episode) (default: ('track', 'episode')).
```

--------------------------------

### Get Single Artist Information

Source: https://spotipy.readthedocs.io/en/master/index.html

Fetches details for a single artist using their ID, URI, or URL.

```python
artist = sp.artist('3jOstUTkEu2JkjvRdBA5Gu')

```

--------------------------------

### Authorization Code Flow Quick Start

Source: https://spotipy.readthedocs.io/en/master/_sources/index.rst.txt

Authenticate using the Authorization Code Flow with a specified scope and retrieve saved tracks. Ensure your Spotify app has a redirect URI configured.

```python
import spotipy
from spotipy.oauth2 import SpotifyOAuth

scope = "user-library-read"

sp = spotipy.Spotify(auth_manager=SpotifyOAuth(scope=scope))

results = sp.current_user_saved_tracks()
for idx, item in enumerate(results['items']):
    track = item['track']
    print(idx, track['artists'][0]['name'], " – ", track['name'])
```

--------------------------------

### GET /episodes/{id}

Source: https://spotipy.readthedocs.io/en/master/index.html

Retrieve information for a single episode.

```APIDOC
## GET /episodes/{id}

### Description
Returns a single episode given the episode’s ID, URIs or URL.

### Method
GET

### Endpoint
/episodes/{id}

### Parameters
#### Path Parameters
- **episode_id** (string) - Required - The episode ID, URI or URL
#### Query Parameters
- **market** (string) - Optional - An ISO 3166-1 alpha-2 country code.
```

--------------------------------

### Get Top Tracks and Album Art

Source: https://spotipy.readthedocs.io/en/master/_sources/index.rst.txt

Fetch the top 10 tracks for an artist, including their preview URLs and the URL of the first image in their album art. This requires the artist's Spotify URI.

```python
import spotipy
from spotipy.oauth2 import SpotifyClientCredentials

lz_uri = 'spotify:artist:36QJpDe2go2KgaRleHCDTp'

spotify = spotipy.Spotify(client_credentials_manager=SpotifyClientCredentials())
results = spotify.artist_top_tracks(lz_uri)

for track in results['tracks'][:10]:
    print('track    : ' + track['name'])
    print('audio    : ' + track['preview_url'])
    print('cover art: ' + track['album']['images'][0]['url'])
    print()
```

--------------------------------

### Get Album

Source: https://spotipy.readthedocs.io/en/master/index.html

Retrieves a single album's details using its ID, URI, or URL.

```APIDOC
## GET /album/{album_id}

### Description
Returns a single album given the album’s ID, URIs or URL.

### Method
GET

### Endpoint
`/album/{album_id}`

### Parameters
#### Path Parameters
- **album_id** (string) - Required - The album ID, URI or URL.

#### Query Parameters
- **market** (string) - Optional - An ISO 3166-1 alpha-2 country code.

### Request Example
```python
sp.album('4aEz2RzP4f7o3f3Q9f3f0f')
```

### Response
#### Success Response (200)
- **album_object** (object) - Detailed information about the album.

#### Response Example
```json
{
  "album_type": "album",
  "artists": [
    {
      "external_urls": {
        "spotify": "https://open.spotify.com/artist/3jOstUTkEu2JkjvRdBA5Gu"
      },
      "href": "https://api.spotify.com/v1/artists/3jOstUTkEu2JkjvRdBA5Gu",
      "id": "3jOstUTkEu2JkjvRdBA5Gu",
      "name": "The Beatles",
      "type": "artist",
      "uri": "spotify:artist:3jOstUTkEu2JkjvRdBA5Gu"
    }
  ],
  "available_markets": [
    "CA",
    "MX",
    "US"
  ],
  "external_urls": {
    "spotify": "https://open.spotify.com/album/4aEz2RzP4f7o3f3Q9f3f0f"
  },
  "href": "https://api.spotify.com/v1/albums/4aEz2RzP4f7o3f3Q9f3f0f",
  "id": "4aEz2RzP4f7o3f3Q9f3f0f",
  "images": [
    {
      "height": 640,
      "url": "https://i.scdn.co/image/abc123def456ghi789jkl",
      "width": 640
    }
  ],
  "name": "Abbey Road",
  "release_date": "1969-09-26",
  "release_date_precision": "day",
  "total_tracks": 17,
  "type": "album",
  "uri": "spotify:album:4aEz2RzP4f7o3f3Q9f3f0f"
}
```
```

--------------------------------

### Get Multiple Artists

Source: https://spotipy.readthedocs.io/en/master/index.html

Retrieves a list of artists using their IDs, URIs, or URLs.

```python
artists = sp.artists(['3jOstUTkEu2JkjvRdBA5Gu', '6v8FB8ljqmv67JOmpGRTPa'])

```

--------------------------------

### Get Album Tracks

Source: https://spotipy.readthedocs.io/en/master/index.html

Fetches tracks for a specific album, with options to limit the number of results and specify the market.

```python
album_tracks = sp.album_tracks('4aEz2Rmp சேர்க்க')

```

--------------------------------

### Get Artist Top Tracks

Source: https://spotipy.readthedocs.io/en/master/index.html

Fetches the top 10 tracks for an artist in a specified country. Defaults to 'US' if no country is provided.

```python
top_tracks = sp.artist_top_tracks('3jOstUTkEu2JkjvRdBA5Gu')

```

--------------------------------

### GET /search

Source: https://spotipy.readthedocs.io/en/master/index.html

Searches for items such as tracks, albums, or artists based on a query string.

```APIDOC
## GET /search

### Description
Searches for an item in the Spotify catalog.

### Method
GET

### Parameters
#### Query Parameters
- **q** (string) - Required - The search query.
- **limit** (integer) - Optional - The number of items to return (min=1, default=10, max=50).
- **offset** (integer) - Optional - The index of the first item to return.
- **type** (string) - Optional - The types of items to return (e.g., 'track,album').
- **market** (string) - Optional - An ISO 3166-1 alpha-2 country code.
```

--------------------------------

### Get Album Information

Source: https://spotipy.readthedocs.io/en/master/index.html

Retrieves details for a single album using its ID, URI, or URL. The 'market' parameter can filter results by country.

```python
album = sp.album('4aEz2Rmp சேர்க்க')

```

--------------------------------

### GET /categories/{category_id}

Source: https://spotipy.readthedocs.io/en/master/index.html

Get info about a category.

```APIDOC
## GET /categories/{category_id}

### Description
Get info about a category.

### Method
GET

### Endpoint
/categories/{category_id}

### Parameters
#### Path Parameters
- **category_id** (string) - Required - The Spotify category ID for the category.

#### Query Parameters
- **country** (string) - Optional - An ISO 3166-1 alpha-2 country code.
- **locale** (string) - Optional - The desired language, consisting of an ISO 639-1 alpha-2 language code and an ISO 3166-1 alpha-2 country code, joined by an underscore.
```

--------------------------------

### Spotify Client Initialization

Source: https://spotipy.readthedocs.io/en/master/index.html

Initializes the Spotify API client with various configuration options.

```APIDOC
## Spotify Client Initialization

### Description
Creates a Spotify API client instance. This client can be used to interact with the Spotify Web API.

### Method
`__init__`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **auth** (optional) - An access token.
- **requests_session** (optional) - A Requests session object or a truthy value to create one. A falsy value disables sessions. It should generally be a good idea to keep sessions enabled for performance reasons (connection pooling).
- **client_credentials_manager** (optional) - SpotifyClientCredentials object.
- **oauth_manager** (optional) - SpotifyOAuth object.
- **auth_manager** (optional) - SpotifyOauth, SpotifyClientCredentials, or SpotifyImplicitGrant object.
- **proxies** (optional) - Definition of proxies. See Requests doc https://2.python-requests.org/en/master/user/advanced/#proxies.
- **requests_timeout** (optional) - Tell Requests to stop waiting for a response after a given number of seconds.
- **status_forcelist** (optional) - Tell requests what type of status codes retries should occur on.
- **retries** (optional) - Total number of retries to allow.
- **status_retries** (optional) - Number of times to retry on bad status codes.
- **backoff_factor** (optional) - A backoff factor to apply between attempts after the second try. See urllib3 https://urllib3.readthedocs.io/en/latest/reference/urllib3.util.html.
- **language** (optional) - The language parameter advertises what language the user prefers to see. See ISO-639-1 language code: https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes.

### Request Example
```python
import spotipy

sp = spotipy.Spotify(auth_manager=spotipy.SpotifyClientCredentials()) # Example with client credentials
```

### Response
None (initializes the object)
```

--------------------------------

### Package and Upload to PyPI

Source: https://spotipy.readthedocs.io/en/master/_sources/index.rst.txt

Commands to build distribution packages and upload them to the PyPI repository.

```bash
python setup.py sdist bdist_wheel
python3 setup.py sdist bdist_wheel
twine check dist/*
twine upload --repository-url https://upload.pypi.org/legacy/ --skip-existing dist/*.(whl|gz|zip)~dist/*linux*.whl
```

--------------------------------

### Set Environment Variables for Credentials

Source: https://spotipy.readthedocs.io/en/master/_sources/index.rst.txt

Set environment variables for Spotify API credentials and redirect URI. Use $env:"credentials" instead of export on Windows.

```bash
export SPOTIPY_CLIENT_ID='your-spotify-client-id'
export SPOTIPY_CLIENT_SECRET='your-spotify-client-secret'
export SPOTIPY_REDIRECT_URI='your-app-redirect-url'
```

--------------------------------

### GET /me/player/currently-playing

Source: https://spotipy.readthedocs.io/en/master/index.html

Get the user's currently playing track.

```APIDOC
## GET /me/player/currently-playing

### Description
Get user’s currently playing track.

### Method
GET

### Endpoint
/me/player/currently-playing

### Parameters
#### Query Parameters
- **market** (string) - Optional - An ISO 3166-1 alpha-2 country code.
- **additional_types** (string) - Optional - 'episode' to get podcast track information
```

--------------------------------

### Export Environment Variables

Source: https://spotipy.readthedocs.io/en/master/_sources/index.rst.txt

Set the required Spotify API credentials and redirect URI as environment variables.

```bash
export SPOTIPY_CLIENT_ID=client_id_here
export SPOTIPY_CLIENT_SECRET=client_secret_here
export SPOTIPY_CLIENT_USERNAME=client_username_here # This is actually an id not spotify display name
export SPOTIPY_REDIRECT_URI=http://127.0.0.1:8080 # Make url is set in app you created to get your ID and SECRET
```

--------------------------------

### SpotifyPKCE Class

Source: https://spotipy.readthedocs.io/en/master/index.html

Implements PKCE Authorization Flow for client apps.

```APIDOC
## SpotifyPKCE Class

### Description
Implements PKCE Authorization Flow for client apps. This auth manager enables user and non-user endpoints with only a client ID, redirect URI, and username. When the app requests an access token for the first time, the user is prompted to authorize the new client app. After authorizing the app, the client app is then given both access and refresh tokens. This is the preferred way of authorizing a mobile/desktop client.

### Methods

#### `__init__`
Creates a SpotifyPKCE object.

**Parameters:**
- **client_id** (str) - Required - Must be supplied or set as environment variable
- **redirect_uri** (str) - Required - Must be supplied or set as environment variable
- **state** (str) - Optional - No verification is performed
- **scope** (str or list) - Optional - Either a list of scopes or comma separated string of scopes. e.g, “playlist-read-private,playlist-read-collaborative”
- **cache_path** (str) - Optional (deprecated) - Will otherwise be generated (takes precedence over username)
- **username** (str) - Optional (deprecated) - Or set as environment variable (will set cache_path to .cache-{username})
- **proxies** (dict) - Optional - Proxy for the requests library to route through
- **requests_timeout** (int) - Optional - Tell Requests to stop waiting for a response after a given number of seconds
- **requests_session** (bool) - Optional - A Requests session
- **open_browser** (bool) - Optional - Whether the web browser should be opened to authorize a user
- **cache_handler** (CacheHandler) - Optional - An instance of the CacheHandler class to handle getting and saving cached authorization tokens. Optional, will otherwise use CacheFileHandler. (takes precedence over cache_path and username)

### Constants
- **OAUTH_AUTHORIZE_URL**: 'https://accounts.spotify.com/authorize'
- **OAUTH_TOKEN_URL**: 'https://accounts.spotify.com/api/token'
```

--------------------------------

### Navigation Methods

Source: https://spotipy.readthedocs.io/en/master/genindex.html

Methods for navigating through playback queues and tracks.

```APIDOC
## next() (spotipy.client.Spotify method)

### Description
Skips to the next track in the queue.

### Method
POST

### Endpoint
/v1/me/player/next

## next_track() (spotipy.client.Spotify method)

### Description
Skips to the next track in the queue.

### Method
POST

### Endpoint
/v1/me/player/next

## previous() (spotipy.client.Spotify method)

### Description
Skips to the previous track in the queue.

### Method
POST

### Endpoint
/v1/me/player/previous

## previous_track() (spotipy.client.Spotify method)

### Description
Skips to the previous track in the queue.

### Method
POST

### Endpoint
/v1/me/player/previous

## queue() (spotipy.client.Spotify method)

### Description
Adds an item to the user's queue.

### Method
POST

### Endpoint
/v1/me/player/queue

### Parameters
#### Query Parameters
- **uri** (str) - Required - The Spotify URI of the item to add.
- **device_id** (str) - Optional - The ID of the device to add the item to.

```

--------------------------------

### Export Environment Variables for Spotipy

Source: https://spotipy.readthedocs.io/en/master/index.html

Set required credentials and configuration as environment variables before running the application.

```bash
export SPOTIPY_CLIENT_ID=client_id_here export SPOTIPY_CLIENT_SECRET=client_secret_here export SPOTIPY_CLIENT_USERNAME=client_username_here # This is actually an id not spotify display name export SPOTIPY_REDIRECT_URI=http://127.0.0.1:8080 # Make url is set in app you created to get your ID and SECRET
```

--------------------------------

### Get Available Recommendation Genres

Source: https://spotipy.readthedocs.io/en/master/index.html

Get a list of genres available for the recommendations function. This endpoint has been removed by Spotify and is no longer available.

```APIDOC
## GET /recommendations/available/genre

### Description
Get a list of genres available for the recommendations function. This endpoint has been removed by Spotify and is no longer available.

### Method
GET

### Endpoint
/recommendations/available/genre
```

--------------------------------

### POST /user_playlist_create

Source: https://spotipy.readthedocs.io/en/master/index.html

Creates a new playlist for a user.

```APIDOC
## POST /user_playlist_create

### Description
Creates a playlist for a user.

### Parameters
#### Request Body
- **user** (string) - Required - The id of the user
- **name** (string) - Required - The name of the playlist
- **public** (boolean) - Optional - Is the created playlist public
- **collaborative** (boolean) - Optional - Is the created playlist collaborative
- **description** (string) - Optional - The description of the playlist
```

--------------------------------

### Get Playlist Tracks (Deprecated)

Source: https://spotipy.readthedocs.io/en/master/index.html

Get full details of the tracks of a playlist. This method is deprecated and may be removed in a future version. Use playlist_items instead.

```APIDOC
## GET /playlists/{playlist_id}/tracks

### Description
Get full details of the tracks of a playlist. This method is deprecated and may be removed in a future version. Use playlist_items(playlist_id, …, additional_types=(‘track’,)) instead.

### Method
GET

### Endpoint
/playlists/{playlist_id}/tracks

### Parameters
#### Path Parameters
- **playlist_id** (string) - Required - The playlist ID, URI or URL.

#### Query Parameters
- **fields** (string) - Optional - Which fields to return.
- **limit** (integer) - Optional - The maximum number of tracks to return (default: 50).
- **offset** (integer) - Optional - The index of the first track to return (default: 0).
- **market** (string) - Optional - An ISO 3166-1 alpha-2 country code.
- **additional_types** (array of strings) - Optional - List of item types to return (valid types are: track and episode) (default: ('track',)).
```

--------------------------------

### Environment Variable Configuration

Source: https://spotipy.readthedocs.io/en/master/index.html

Configuring Spotify application credentials via environment variables for secure access.

```APIDOC
## Environment Variable Configuration

### Description
Set these environment variables to avoid hardcoding credentials in your source code.

### Variables
- **SPOTIPY_CLIENT_ID** - Your Spotify application client ID
- **SPOTIPY_CLIENT_SECRET** - Your Spotify application client secret
- **SPOTIPY_REDIRECT_URI** - Your application redirect URL
```

--------------------------------

### Token Management

Source: https://spotipy.readthedocs.io/en/master/index.html

Functions for getting and managing access tokens.

```APIDOC
## get_access_token

### Description
Gets the access token for the app. If the code is not given and no cached token is used, an authentication window will be shown to the user to get a new code.

### Parameters
- **code** (string) - Optional - The response code from authentication
- **check_cache** (bool) - Optional - If true, checks for a locally stored token before requesting a new token

## get_cached_token

### Description
Retrieves a cached token if available.

## refresh_access_token

### Description
Refreshes the access token using a refresh token.

### Parameters
- **refresh_token** (string) - Required - The refresh token to use for obtaining a new access token.

## validate_token

### Description
Validates the provided token information.

### Parameters
- **token_info** (dict) - Required - The token information to validate.
```

--------------------------------

### Set Spotify Credentials

Source: https://spotipy.readthedocs.io/en/master/_sources/index.rst.txt

Set your Spotify API client ID and client secret as environment variables before running your application.

```bash
export SPOTIPY_CLIENT_ID='your-spotify-client-id'
export SPOTIPY_CLIENT_SECRET='your-spotify-client-secret'
```

--------------------------------

### GET /shows/{show_id}

Source: https://spotipy.readthedocs.io/en/master/index.html

Retrieves metadata for a specific show.

```APIDOC
## GET /shows/{show_id}

### Description
Returns a single show given the show’s ID, URIs or URL.

### Method
GET

### Parameters
#### Path Parameters
- **show_id** (string) - Required - The show ID, URI or URL.

#### Query Parameters
- **market** (string) - Optional - An ISO 3166-1 alpha-2 country code.
```

--------------------------------

### Auth Manager Initialization

Source: https://spotipy.readthedocs.io/en/master/index.html

Initializes the Auth Manager with various parameters for the PKCE Auth flow.

```APIDOC
## __init__

### Description
Creates Auth Manager with the PKCE Auth flow.

### Parameters
- **client_id** (string) - Required - Must be supplied or set as environment variable
- **redirect_uri** (string) - Required - Must be supplied or set as environment variable
- **state** (string) - Optional - No verification is performed
- **scope** (string or list) - Optional - Either a list of scopes or comma separated string of scopes. e.g, ‘playlist-read-private,playlist-read-collaborative’
- **cache_path** (string) - Optional (deprecated) - Will otherwise be generated (takes precedence over username)
- **username** (string) - Optional (deprecated) - Or set as environment variable (will set cache_path to .cache-{username})
- **proxies** (dict) - Optional - Proxy for the requests library to route through
- **requests_timeout** (int) - Optional - Tell Requests to stop waiting for a response after a given number of seconds
- **requests_session** (bool or requests.Session) - Optional - A Requests session
- **open_browser** (bool) - Optional - Whether the web browser should be opened to authorize a user
- **cache_handler** (CacheHandler) - Optional - An instance of the CacheHandler class to handle getting and saving cached authorization tokens. Will otherwise use CacheFileHandler. (takes precedence over cache_path and username)
```

--------------------------------

### POST /users/playlists

Source: https://spotipy.readthedocs.io/en/master/index.html

Creates a playlist for the current user.

```APIDOC
## POST /users/playlists

### Description
Creates a playlist for the current user.

### Method
POST

### Endpoint
/users/playlists

### Parameters
#### Request Body
- **name** (string) - Required - The name of the playlist
- **public** (boolean) - Optional - Is the created playlist public
- **collaborative** (boolean) - Optional - Is the created playlist collaborative
- **description** (string) - Optional - The description of the playlist
```

--------------------------------

### SpotifyOAuth Authentication

Source: https://spotipy.readthedocs.io/en/master/index.html

Demonstrates how to initialize the Spotify client using the Authorization Code flow for user-authorized requests.

```APIDOC
## SpotifyOAuth Authentication

### Description
Initializes the Spotify client using the SpotifyOAuth manager to handle user authorization and token management.

### Usage
```python
import spotipy
from spotipy.oauth2 import SpotifyOAuth

scope = "user-library-read"
sp = spotipy.Spotify(auth_manager=SpotifyOAuth(scope=scope))
```
```

--------------------------------

### Track and Show Methods

Source: https://spotipy.readthedocs.io/en/master/genindex.html

Methods for retrieving information about tracks and shows.

```APIDOC
## show() (spotipy.client.Spotify method)

### Description
Gets a podcast show.

### Method
GET

### Endpoint
/v1/shows/{id}

### Parameters
#### Path Parameters
- **id** (str) - Required - The Spotify ID of the show.
#### Query Parameters
- **market** (str) - Optional - The market to consider.

## show_episodes() (spotipy.client.Spotify method)

### Description
Gets all episodes for a podcast show.

### Method
GET

### Endpoint
/v1/shows/{id}/episodes

### Parameters
#### Path Parameters
- **id** (str) - Required - The Spotify ID of the show.
#### Query Parameters
- **market** (str) - Optional - The market to consider.
- **limit** (int) - Optional - The maximum number of items to return.
- **offset** (int) - Optional - The offset from the first item.

## shows() (spotipy.client.Spotify method)

### Description
Gets multiple shows.

### Method
GET

### Endpoint
/v1/shows

### Parameters
#### Query Parameters
- **ids** (list[str]) - Required - A comma-separated list of Spotify show IDs.
- **market** (str) - Optional - The market to consider.

## track() (spotipy.client.Spotify method)

### Description
Gets a Spotify track.

### Method
GET

### Endpoint
/v1/tracks/{id}

### Parameters
#### Path Parameters
- **id** (str) - Required - The Spotify ID of the track.
#### Query Parameters
- **market** (str) - Optional - The market to consider.

## tracks() (spotipy.client.Spotify method)

### Description
Gets multiple tracks.

### Method
GET

### Endpoint
/v1/tracks

### Parameters
#### Query Parameters
- **ids** (list[str]) - Required - A comma-separated list of Spotify track IDs.
- **market** (str) - Optional - The market to consider.

```

--------------------------------

### GET /tracks

Source: https://spotipy.readthedocs.io/en/master/index.html

Retrieves a list of tracks by their IDs, URIs, or URLs.

```APIDOC
## GET /tracks

### Description
Returns a list of tracks given a list of track IDs, URIs, or URLs. Maximum: 50 IDs.

### Parameters
#### Query Parameters
- **tracks** (list) - Required - A list of spotify URIs, URLs or IDs
- **market** (string) - Optional - An ISO 3166-1 alpha-2 country code.
```

--------------------------------

### GET /track

Source: https://spotipy.readthedocs.io/en/master/index.html

Retrieves a single track by its ID, URI, or URL.

```APIDOC
## GET /track

### Description
Returns a single track given the track’s ID, URI or URL.

### Parameters
#### Query Parameters
- **track_id** (string) - Required - A spotify URI, URL or ID
- **market** (string) - Optional - An ISO 3166-1 alpha-2 country code.
```

--------------------------------

### Changelog Entry Template

Source: https://spotipy.readthedocs.io/en/master/_sources/index.rst.txt

Format for adding new entries to the project changelog.

```markdown
## Unreleased

// Add your changes here and then delete this line
```

--------------------------------

### Get Playlist Cover Image

Source: https://spotipy.readthedocs.io/en/master/index.html

Retrieves the cover image of a playlist.

```APIDOC
## GET /playlists/{playlist_id}/images

### Description
Get cover image of a playlist.

### Method
GET

### Endpoint
/playlists/{playlist_id}/images

### Parameters
#### Path Parameters
- **playlist_id** (string) - Required - The playlist ID, URI or URL.
```

--------------------------------

### Get Previous Result

Source: https://spotipy.readthedocs.io/en/master/index.html

Returns the previous result given a paged result.

```APIDOC
## GET /previous

### Description
Returns the previous result given a paged result.

### Method
GET

### Endpoint
/previous

### Parameters
#### Query Parameters
- **result** (object) - Required - A previously returned paged result.
```

--------------------------------

### User Following Methods

Source: https://spotipy.readthedocs.io/en/master/genindex.html

Methods for managing the artists and users that the current user follows.

```APIDOC
## user_follow_artists() (spotipy.client.Spotify method)

### Description
Adds Spotify artists to the current user's followed artists.

### Method
PUT

### Endpoint
/v1/me/following

### Parameters
#### Query Parameters
- **ids** (list[str]) - Required - A comma-separated list of Spotify artist IDs.
#### Request Body
- **action** (str) - Required - The action to perform, e.g., 'follow' or 'unfollow'.

## user_follow_users() (spotipy.client.Spotify method)

### Description
Adds Spotify users to the current user's followed users.

### Method
PUT

### Endpoint
/v1/me/following

### Parameters
#### Query Parameters
- **ids** (list[str]) - Required - A comma-separated list of Spotify user IDs.
#### Request Body
- **action** (str) - Required - The action to perform, e.g., 'follow' or 'unfollow'.

## user_unfollow_artists() (spotipy.client.Spotify method)

### Description
Removes Spotify artists from the current user's followed artists.

### Method
DELETE

### Endpoint
/v1/me/following

### Parameters
#### Query Parameters
- **ids** (list[str]) - Required - A comma-separated list of Spotify artist IDs.
#### Request Body
- **action** (str) - Required - The action to perform, e.g., 'follow' or 'unfollow'.

## user_unfollow_users() (spotipy.client.Spotify method)

### Description
Removes Spotify users from the current user's followed users.

### Method
DELETE

### Endpoint
/v1/me/following

### Parameters
#### Query Parameters
- **ids** (list[str]) - Required - A comma-separated list of Spotify user IDs.
#### Request Body
- **action** (str) - Required - The action to perform, e.g., 'follow' or 'unfollow'.

```

--------------------------------

### Get Artists

Source: https://spotipy.readthedocs.io/en/master/index.html

Retrieves a list of artists using their IDs, URIs, or URLs.

```APIDOC
## GET /artists

### Description
Returns a list of artists given the artist IDs, URIs, or URLs.

### Method
GET

### Endpoint
`/artists`

### Parameters
#### Path Parameters
None

#### Query Parameters
- **artists** (list of strings) - Required - A list of artist IDs, URIs or URLs.

### Request Example
```python
sp.artists(['3jOstUTkEu2JkjvRdBA5Gu', '1234567890abcdef'])
```

### Response
#### Success Response (200)
- **artists_object** (object) - Contains a list of artist objects.

#### Response Example
```json
{
  "artists": [
    {
      "external_urls": {
        "spotify": "https://open.spotify.com/artist/3jOstUTkEu2JkjvRdBA5Gu"
      },
      "followers": {
        "href": null,
        "total": 10000000
      },
      "genres": [
        "rock",
        "classic rock",
        "the beatles"
      ],
      "href": "https://api.spotify.com/v1/artists/3jOstUTkEu2JkjvRdBA5Gu",
      "id": "3jOstUTkEu2JkjvRdBA5Gu",
      "images": [
        {
          "height": 640,
          "url": "https://i.scdn.co/image/abcdef1234567890",
          "width": 640
        }
      ],
      "name": "The Beatles",
      "popularity": 90,
      "type": "artist",
      "uri": "spotify:artist:3jOstUTkEu2JkjvRdBA5Gu"
    }
  ]
}
```
```

--------------------------------

### User Playlist Methods

Source: https://spotipy.readthedocs.io/en/master/genindex.html

Methods for managing playlists owned by the current user.

```APIDOC
## user_playlist() (spotipy.client.Spotify method)

### Description
Gets a playlist owned by a Spotify user.

### Method
GET

### Endpoint
/v1/users/{user_id}/playlists/{playlist_id}

### Parameters
#### Path Parameters
- **user_id** (str) - Required - The Spotify ID of the user.
- **playlist_id** (str) - Required - The Spotify ID of the playlist.
#### Query Parameters
- **fields** (str) - Optional - Filters for the fields to return.

## user_playlist_add_episodes() (spotipy.client.Spotify method)

### Description
Adds one or more episodes to a user's playlist.

### Method
POST

### Endpoint
/v1/users/{user_id}/playlists/{playlist_id}/episodes

### Parameters
#### Path Parameters
- **user_id** (str) - Required - The Spotify ID of the user.
- **playlist_id** (str) - Required - The Spotify ID of the playlist.
#### Request Body
- **uris** (list[str]) - Required - A list of Spotify URIs for the episodes to add.
- **position** (int) - Optional - The position to insert the episodes at.

## user_playlist_add_tracks() (spotipy.client.Spotify method)

### Description
Adds one or more tracks to a user's playlist.

### Method
POST

### Endpoint
/v1/users/{user_id}/playlists/{playlist_id}/tracks

### Parameters
#### Path Parameters
- **user_id** (str) - Required - The Spotify ID of the user.
- **playlist_id** (str) - Required - The Spotify ID of the playlist.
#### Request Body
- **uris** (list[str]) - Required - A list of Spotify URIs for the tracks to add.
- **position** (int) - Optional - The position to insert the tracks at.

## user_playlist_change_details() (spotipy.client.Spotify method)

### Description
Changes a playlist's details.

### Method
PUT

### Endpoint
/v1/users/{user_id}/playlists/{playlist_id}

### Parameters
#### Path Parameters
- **user_id** (str) - Required - The Spotify ID of the user.
- **playlist_id** (str) - Required - The Spotify ID of the playlist.
#### Request Body
- **name** (str) - Optional - The new name for the playlist.
- **public** (bool) - Optional - Whether the playlist should be public.
- **collaborative** (bool) - Optional - Whether the playlist should be collaborative.
- **description** (str) - Optional - The new description for the playlist.

## user_playlist_create() (spotipy.client.Spotify method)

### Description
Creates a playlist for a user.

### Method
POST

### Endpoint
/v1/users/{user_id}/playlists

### Parameters
#### Path Parameters
- **user_id** (str) - Required - The Spotify ID of the user.
#### Request Body
- **name** (str) - Required - The name for the playlist.
- **public** (bool) - Optional - Whether the playlist should be public.
- **collaborative** (bool) - Optional - Whether the playlist should be collaborative.
- **description** (str) - Optional - The description for the playlist.

## user_playlist_follow_playlist() (spotipy.client.Spotify method)

### Description
Adds the current user as a follower of a playlist.

### Method
PUT

### Endpoint
/v1/playlists/{playlist_id}/followers

### Parameters
#### Path Parameters
- **playlist_id** (str) - Required - The Spotify ID of the playlist.
#### Request Body
- **public** (bool) - Optional - Whether the playlist should be public.

## user_playlist_is_following() (spotipy.client.Spotify method)

### Description
Checks if the current user is following a playlist.

### Method
GET

### Endpoint
/v1/playlists/{playlist_id}/followers/contains

### Parameters
#### Path Parameters
- **playlist_id** (str) - Required - The Spotify ID of the playlist.
#### Query Parameters
- **ids** (list[str]) - Required - A list of Spotify user IDs to check.

## user_playlist_remove_all_occurrences_of_tracks() (spotipy.client.Spotify method)

### Description
Removes all occurrences of one or more tracks from a user's playlist.

### Method
DELETE

### Endpoint
/v1/users/{user_id}/playlists/{playlist_id}/tracks

### Parameters
#### Path Parameters
- **user_id** (str) - Required - The Spotify ID of the user.
- **playlist_id** (str) - Required - The Spotify ID of the playlist.
#### Request Body
- **tracks** (list[dict]) - Required - A list of track objects to remove. Each object should contain a "uri" and optionally a "positions" list.

## user_playlist_remove_specific_occurrences_of_tracks() (spotipy.client.Spotify method)

### Description
Removes specific occurrences of one or more tracks from a user's playlist.

### Method
DELETE

### Endpoint
/v1/users/{user_id}/playlists/{playlist_id}/tracks

### Parameters
#### Path Parameters
- **user_id** (str) - Required - The Spotify ID of the user.
- **playlist_id** (str) - Required - The Spotify ID of the playlist.
#### Request Body
- **tracks** (list[dict]) - Required - A list of track objects to remove. Each object should contain a "uri" and a "positions" list.

## user_playlist_reorder_tracks() (spotipy.client.Spotify method)

### Description
Reorders items in a user's playlist.

### Method
PUT

### Endpoint
/v1/users/{user_id}/playlists/{playlist_id}/tracks

### Parameters
#### Path Parameters
- **user_id** (str) - Required - The Spotify ID of the user.
- **playlist_id** (str) - Required - The Spotify ID of the playlist.
#### Request Body
- **insert_before** (int) - Required - The position to insert the items before.
- **range_start** (int) - Required - The position of the first item to move.
- **range_length** (int) - Required - The number of items to move.
- **snapshot_id** (str) - Optional - The playlist's snapshot ID.

## user_playlist_replace_tracks() (spotipy.client.Spotify method)

### Description
Replaces all items in a user's playlist with new items.

### Method
PUT

### Endpoint
/v1/users/{user_id}/playlists/{playlist_id}/tracks

### Parameters
#### Path Parameters
- **user_id** (str) - Required - The Spotify ID of the user.
- **playlist_id** (str) - Required - The Spotify ID of the playlist.
#### Request Body
- **uris** (list[str]) - Required - A list of Spotify URIs for the new items.

## user_playlist_tracks() (spotipy.client.Spotify method)

### Description
Gets a list of tracks in a user's playlist.

### Method
GET

### Endpoint
/v1/users/{user_id}/playlists/{playlist_id}/tracks

### Parameters
#### Path Parameters
- **user_id** (str) - Required - The Spotify ID of the user.
- **playlist_id** (str) - Required - The Spotify ID of the playlist.
#### Query Parameters
- **fields** (str) - Optional - Filters for the fields to return.
- **limit** (int) - Optional - The maximum number of items to return.
- **offset** (int) - Optional - The offset from the first item.

## user_playlist_unfollow() (spotipy.client.Spotify method)

### Description
Removes the current user as a follower of a playlist.

### Method
DELETE

### Endpoint
/v1/playlists/{playlist_id}/followers

### Parameters
#### Path Parameters
- **playlist_id** (str) - Required - The Spotify ID of the playlist.

```
Tokens:
Raw