Spotipy

https://spotipy.readthedocs.io/en/latest/
Admin
Spotipy is a lightweight Python library that provides full access to the Spotify Web API for...
Tokens:62,340
Snippets:558
Trust Score:9.6
Update:1 day ago
Show doc for...
Tokens:
Raw
### Create virtual environment, install dependencies, and run tests

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

Commands to set up a Python 3.12 virtual environment, install the package in editable mode, and run the test suite.

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

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

### Install Spotipy with pip

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

Use this command to install or upgrade Spotipy to the latest version.

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

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

### start_playback(device_id=None, context_uri=None, uris=None, offset=None, position_ms=None)

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

Starts or resumes the user's playback. Can specify a context URI, a list of track URIs, an offset, and a starting position.

```APIDOC
## start_playback(device_id=None, context_uri=None, uris=None, offset=None, position_ms=None)

### Description
Start or resume user's playback. Provide a context_uri to start playback of an album, artist, or playlist. Provide a uris list to start playback of one or more tracks. Provide offset as {"position": <int>} or {"uri": "<track uri>"} to start playback at a particular offset.

### Method
start_playback

### Parameters
- **device_id** (string) - Optional - Device target for playback.
- **context_uri** (string) - Optional - Spotify context uri to play.
- **uris** (list) - Optional - Spotify track uris.
- **offset** (dict) - Optional - Offset into context by index or track.
- **position_ms** (integer) - Optional - Indicates from what position to start playback. Must be a positive number. Passing in a position that is greater than the length of the track will cause the player to start playing the next song.

```

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

### SpotifyPKCE.get_pkce_handshake_parameters

Source: https://spotipy.readthedocs.io/en/latest/

Gets the PKCE handshake parameters.

```APIDOC
## SpotifyPKCE.get_pkce_handshake_parameters

### Description
Gets the PKCE handshake parameters.

### Method
Method
```

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

### Verify code style with flake8

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

Installs flake8 and runs it to check code style compliance.

```bash
pip install flake8
flake8 .
```

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

### SpotifyPKCE.get_authorize_url

Source: https://spotipy.readthedocs.io/en/latest/

Gets the URL to use to authorize this app.

```APIDOC
## SpotifyPKCE.get_authorize_url

### Description
Gets the URL to use to authorize this app.

### Method
Method

### Parameters
- **state** (string) - Optional - The state parameter for the authorization request
```

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

### SpotifyPKCE.get_authorize_url

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

Gets the URL to use to authorize this app.

```APIDOC
## SpotifyPKCE.get_authorize_url

### Description
Gets the URL to use to authorize this app.

### Method
Method

### Signature
`get_authorize_url(state=None)`

### Parameters
- **state** (str) - Optional - The state parameter to include in the authorization URL.
```

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

### SpotifyImplicitGrant.get_authorize_url

Source: https://spotipy.readthedocs.io/en/latest/

Gets the URL to use to authorize this app.

```APIDOC
## SpotifyImplicitGrant.get_authorize_url

### Description
Gets the URL to use to authorize this app.

### Method
Function

### Signature
get_authorize_url(state=None)

### Parameters
- **state** (string) - Optional - May be given.

### Response
Returns the authorization URL.
```

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

### queue

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

Gets the current user's queue.

```APIDOC
## queue()

### Description
Gets the current user's queue.
```

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

### Verify import sorting with isort

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

Installs isort and checks that import lists are stored correctly.

```bash
pip install isort
isort . -c -v
```

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

### SpotifyImplicitGrant.get_auth_response

Source: https://spotipy.readthedocs.io/en/latest/

Gets a new auth token with user interaction.

```APIDOC
## SpotifyImplicitGrant.get_auth_response

### Description
Gets a new auth **token** with user interaction.

### Method
Function

### Signature
get_auth_response(state=None)

### Parameters
- **state** (string) - Optional - May be given.

### Response
Returns the auth response containing the token.
```

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

### user(user)

Source: https://spotipy.readthedocs.io/en/latest/

Gets basic profile information about a Spotify User.

```APIDOC
## user(user)

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

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

```

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

### user(user)

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

Gets basic profile information about a Spotify User.

```APIDOC
## user(user)

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

### Method
user

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

```

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

### new_releases(country=None, limit=20, offset=0)

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

Get a list of new album releases featured in Spotify.

```APIDOC
## new_releases(country=None, limit=20, offset=0)

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

### Parameters
- **country** (string) - Optional - An ISO 3166-1 alpha-2 country code.
- **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 (the first object). Use with limit to get the next set of items.

```

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

### get_audiobooks(ids, market=None)

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

Get Spotify catalog information for multiple audiobooks based on their Spotify IDs.

```APIDOC
## get_audiobooks(ids, market=None)

### Description
Get Spotify catalog information for multiple audiobooks based on their Spotify IDs.

### Parameters
- **ids** (list) - Required - A list of Spotify IDs for the audiobooks.
- **market** (string) - Optional - An ISO 3166-1 alpha-2 country code.

```

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

### Example usage of Spotify client

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

Shows how to create a Spotify client and fetch an artist and a user. Requires a valid access token or authentication manager.

```python
import spotipy

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

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

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

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

### SpotifyPKCE.get_access_token

Source: https://spotipy.readthedocs.io/en/latest/

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.

```APIDOC
## SpotifyPKCE.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.

### Method
Method

### 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_audiobook_chapters(id, market=None, limit=20, offset=0)

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

Get Spotify catalog information about an audiobook's chapters.

```APIDOC
## get_audiobook_chapters(id, market=None, limit=20, offset=0)

### Description
Get Spotify catalog information about an audiobook's chapters.

### Parameters
- **id** (string) - Required - The Spotify ID for the audiobook.
- **market** (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.

```

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

### recommendations

Source: https://spotipy.readthedocs.io/en/latest/

Gets a list of recommended tracks for one to five seeds. This endpoint has been removed by Spotify and is no longer available.

```APIDOC
## recommendations(seed_artists=None, seed_genres=None, seed_tracks=None, limit=20, country=None, **kwargs)

### 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.

### Parameters
- **seed_artists** (list) - Optional - A list of artist IDs, URIs or URLs.
- **seed_genres** (list) - Optional - A list of genre names.
- **seed_tracks** (list) - Optional - A list of track IDs, URIs or URLs.
- **limit** (integer) - Optional - The maximum number of recommendations to return.
- **country** (string) - Optional - An ISO 3166-1 alpha-2 country code.
- **kwargs** - Optional - Additional keyword arguments.
```

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

### spotipy.client.Spotify.__init__

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

Constructor for the Spotify client class.

```APIDOC
## spotipy.client.Spotify.__init__

### Description
Initializes a new Spotify client instance.

### Method
Constructor

### Signature
`Spotify.__init__(self, ...)`

### Parameters
No parameters are explicitly documented in the source.

### Response
No return value is documented.
```

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

### SpotifyPKCE.get_access_token

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

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.

```APIDOC
## SpotifyPKCE.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.

### Method
Method

### Signature
`get_access_token(code=None, check_cache=True)`

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

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

### SpotifyPKCE.__init__

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

Creates an Auth Manager with the PKCE Auth flow. Accepts client ID, redirect URI, scope, and other optional parameters.

```APIDOC
## SpotifyPKCE.__init__

### Description
Creates an Auth Manager with the PKCE Auth flow. This constructor initializes the manager with the provided client ID, redirect URI, and other optional settings.

### Method
Constructor

### Signature
`__init__(client_id=None, redirect_uri=None, state=None, scope=None, cache_path=None, username=None, proxies=None, requests_timeout=None, requests_session=True, open_browser=True, cache_handler=None)`

### Parameters
- **client_id** (str) - Optional - Must be supplied or set as environment variable.
- **redirect_uri** (str) - Optional - Must be supplied or set as environment variable.
- **state** (str) - Optional - No verification is performed.
- **scope** (list or str) - 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. Optional 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** (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. Takes precedence over cache_path and username.
```

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

### SpotifyPKCE.__init__

Source: https://spotipy.readthedocs.io/en/latest/

Creates an Auth Manager with the PKCE Auth flow. Accepts client ID, redirect URI, and optional parameters for state, scope, caching, proxies, and more.

```APIDOC
## SpotifyPKCE.__init__

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

### Method
Constructor

### 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** (list or string) - 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** (number) - Optional - Tell Requests to stop waiting for a response after a given number of seconds
- **requests_session** (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)
```

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

### SpotifyPKCE.get_cached_token

Source: https://spotipy.readthedocs.io/en/latest/

Gets the cached token.

```APIDOC
## SpotifyPKCE.get_cached_token

### Description
Gets the cached token.

### Method
Method
```

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

### spotipy.oauth2.SpotifyPKCE.__init__

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

Constructor for the SpotifyPKCE class.

```APIDOC
## spotipy.oauth2.SpotifyPKCE.__init__

### Description
Initializes a SpotifyPKCE instance.

### Method
Constructor

### Signature
`SpotifyPKCE.__init__(self, ...)`

### Parameters
No parameters are explicitly documented in the source.

### Response
No return value is documented.
```

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

### spotipy.client.SpotifyException.__init__

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

Constructor for the SpotifyException class.

```APIDOC
## spotipy.client.SpotifyException.__init__

### Description
Initializes a SpotifyException instance.

### Method
Constructor

### Signature
`SpotifyException.__init__(self, ...)`

### Parameters
No parameters are explicitly documented in the source.

### Response
No return value is documented.
```

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

### SpotifyOAuth.get_authorization_code

Source: https://spotipy.readthedocs.io/en/latest/

Gets the authorization code.

```APIDOC
## SpotifyOAuth.get_authorization_code

### Description
Gets the authorization code.

### Method
Function

### Parameters
- **response** (string) - Optional - The response.

### Response
Returns the authorization code.
```

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

### SpotifyOAuth.get_auth_response

Source: https://spotipy.readthedocs.io/en/latest/

Gets the authentication response.

```APIDOC
## SpotifyOAuth.get_auth_response

### Description
Gets the authentication response.

### Method
Function

### Parameters
- **open_browser** (bool) - Optional - Whether to open the browser.

### Response
Returns the authentication response.
```

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

### playlist

Source: https://spotipy.readthedocs.io/en/latest/

Gets playlist by id.

```APIDOC
## playlist

### Description
Gets playlist by id.

### Method
GET

### Endpoint
Not specified

### Parameters
#### Path Parameters
- **playlist_id** (string) - Required - The id of the playlist

#### Query Parameters
- **fields** (string) - Optional - Which fields to return
- **market** (string) - Optional - An ISO 3166-1 alpha-2 country code or the string from_token.
- **additional_types** (tuple) - Optional - List of item types to return. Valid types are: track and episode. Default: ('track',)

### Response
Not specified
```

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

### category

Source: https://spotipy.readthedocs.io/en/latest/

Get info about a category.

```APIDOC
## category

### Description
Get info about a category.

### Parameters
- **category_id** - The Spotify category ID for the category.
- **country** - An ISO 3166-1 alpha-2 country code.
- **locale** - 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.
```

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

### start_playback(device_id=None, context_uri=None, uris=None, offset=None, position_ms=None)

Source: https://spotipy.readthedocs.io/en/latest/

Starts or resumes the user's playback. Can specify a context URI, a list of track URIs, an offset, and a position in milliseconds.

```APIDOC
## start_playback(device_id=None, context_uri=None, uris=None, offset=None, position_ms=None)

### Description
Start or resume user's playback. Provide a context_uri to start playback of an album, artist, or playlist. Provide a uris list to start playback of one or more tracks. Provide offset as {"position": <int>} or {"uri": "<track uri>"} to start playback at a particular offset.

### Parameters
- **device_id** (string) - Optional - device target for playback
- **context_uri** (string) - Optional - spotify context uri to play
- **uris** (list) - Optional - spotify track uris
- **offset** (dict) - Optional - offset into context by index or track
- **position_ms** (int) - Optional - indicates from what position to start playback. Must be a positive number. Passing in a position that is greater than the length of the track will cause the player to start playing the next song.

```

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

### spotipy.oauth2.SpotifyStateError.__init__

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

Constructor for the SpotifyStateError class.

```APIDOC
## spotipy.oauth2.SpotifyStateError.__init__

### Description
Initializes a SpotifyStateError instance.

### Method
Constructor

### Signature
`SpotifyStateError.__init__(self, ...)`

### Parameters
No parameters are explicitly documented in the source.

### Response
No return value is documented.
```

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

### categories

Source: https://spotipy.readthedocs.io/en/latest/

Get a list of categories.

```APIDOC
## categories

### Description
Get a list of categories.

### Parameters
- **country** - An ISO 3166-1 alpha-2 country code.
- **locale** - 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** - The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50
- **offset** - The index of the first item to return. Default: 0 (the first object). Use with limit to get the next set of items.
```

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

### spotipy.oauth2.SpotifyClientCredentials.__init__

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

Constructor for the SpotifyClientCredentials class.

```APIDOC
## spotipy.oauth2.SpotifyClientCredentials.__init__

### Description
Initializes a SpotifyClientCredentials instance.

### Method
Constructor

### Signature
`SpotifyClientCredentials.__init__(self, ...)`

### Parameters
No parameters are explicitly documented in the source.

### Response
No return value is documented.
```

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

### SpotifyPKCE.get_authorization_code

Source: https://spotipy.readthedocs.io/en/latest/

Gets the authorization code from the response.

```APIDOC
## SpotifyPKCE.get_authorization_code

### Description
Gets the authorization code from the response.

### Method
Method

### Parameters
- **response** (string) - Optional - The response from the authorization server
```

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

### spotipy.oauth2.SpotifyOAuth.__init__

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

Constructor for the SpotifyOAuth class.

```APIDOC
## spotipy.oauth2.SpotifyOAuth.__init__

### Description
Initializes a SpotifyOAuth instance.

### Method
Constructor

### Signature
`SpotifyOAuth.__init__(self, ...)`

### Parameters
No parameters are explicitly documented in the source.

### Response
No return value is documented.
```

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

### playlist_cover_image

Source: https://spotipy.readthedocs.io/en/latest/

Get cover image of a playlist.

```APIDOC
## playlist_cover_image

### Description
Get cover image of a playlist.

### Method
GET

### Endpoint
Not specified

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

### Response
Not specified
```

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

### user_playlist_create(user, name, public=True, collaborative=False, description='')

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

Creates a playlist for a user.

```APIDOC
## user_playlist_create(user, name, public=True, collaborative=False, description='')

### Description
Creates a playlist for a user.

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

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

### user_playlist_create(user, name, public=True, collaborative=False, description='')

Source: https://spotipy.readthedocs.io/en/latest/

Creates a playlist for a user.

```APIDOC
## user_playlist_create(user, name, public=True, collaborative=False, description='')

### Description
Creates a playlist for a user.

### Parameters
- **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.
```

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

### SpotifyOAuth.get_authorization_code

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

Gets the authorization code from the response.

```APIDOC
## SpotifyOAuth.get_authorization_code

### Description
Gets the authorization code from the response.

### Method
Function

### Parameters
- **response** (str) - Optional - The response from the authorization server.

### Returns
- **code** (str) - The authorization code.

### Example
```python
code = sp_oauth.get_authorization_code(response="http://callback?code=...")
```
```

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

### SpotifyOAuth.get_auth_response

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

Gets the authentication response from the user.

```APIDOC
## SpotifyOAuth.get_auth_response

### Description
Gets the authentication response from the user.

### Method
Function

### Parameters
- **open_browser** (bool) - Optional - Whether to open the browser for authorization.

### Returns
- **response** (str) - The authentication response.

### Example
```python
response = sp_oauth.get_auth_response()
```
```

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

### spotipy.oauth2.SpotifyImplicitGrant.__init__

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

Constructor for the SpotifyImplicitGrant class.

```APIDOC
## spotipy.oauth2.SpotifyImplicitGrant.__init__

### Description
Initializes a SpotifyImplicitGrant instance.

### Method
Constructor

### Signature
`SpotifyImplicitGrant.__init__(self, ...)`

### Parameters
No parameters are explicitly documented in the source.

### Response
No return value is documented.
```

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

### SpotifyOAuth.__init__

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

Creates a SpotifyOAuth object with the specified client credentials, redirect URI, scope, and optional caching and session parameters.

```APIDOC
## SpotifyOAuth.__init__

### Description
Creates a SpotifyOAuth object for the Authorization Code Flow.

### Method
Constructor

### Parameters
- **client_id** (str) - Optional - Must be supplied or set as environment variable.
- **client_secret** (str) - Optional - Must be supplied or set as environment variable.
- **redirect_uri** (str) - Optional - Must be supplied or set as environment variable.
- **state** (str) - Optional - No verification is performed.
- **scope** (list or str) - 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.
- **show_dialog** (bool) - Optional - Interpreted as boolean.
- **requests_session** (requests.Session) - Optional - A Requests session.
- **requests_timeout** (float) - Optional - Tell Requests to stop waiting for a response after a given number of seconds.
- **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. Takes precedence over cache_path and username.

### Example
```python
sp_oauth = SpotifyOAuth(
    client_id="your_client_id",
    client_secret="your_client_secret",
    redirect_uri="http://localhost:8080/callback",
    scope="playlist-read-private"
)
```
```

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

### Package and upload to PyPI

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

Commands to build distributions, check them with twine, and upload to PyPI. The command includes a repository URL and skips existing files.

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

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

### SpotifyOAuth.get_authorize_url

Source: https://spotipy.readthedocs.io/en/latest/

Gets the URL to use to authorize this app.

```APIDOC
## SpotifyOAuth.get_authorize_url

### Description
Gets the URL to use to authorize this app.

### Method
Function

### Parameters
- **state** (string) - Optional - The state parameter.

### Response
Returns the authorization URL.
```

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

### Get 30 second samples and cover art for top 10 Led Zeppelin tracks

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

Uses SpotifyClientCredentials and artist_top_tracks to fetch the top tracks for an artist, then prints the track name, preview URL, and cover art URL for the first 10 tracks.

```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()
```

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

### Set SPOTIPY_CLIENT_ID and SPOTIPY_CLIENT_SECRET environment variables

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

Required environment variables for the Client Credentials Flow. No SPOTIPY_REDIRECT_URI is needed, so the browser sign-in page is never shown.

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

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

### SpotifyOAuth.get_authorize_url

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

Gets the URL to use to authorize this app.

```APIDOC
## SpotifyOAuth.get_authorize_url

### Description
Gets the URL to use to authorize this app.

### Method
Function

### Parameters
- **state** (str) - Optional - The state parameter for the authorization request.

### Returns
- **url** (str) - The authorization URL.

### Example
```python
auth_url = sp_oauth.get_authorize_url()
```
```

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

### Set SPOTIPY_CLIENT_ID and SPOTIPY_CLIENT_SECRET environment variables

Source: https://spotipy.readthedocs.io/en/latest/

Required for Client Credentials Flow. No SPOTIPY_REDIRECT_URI is needed, so no browser redirect occurs.

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

```

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

### playlist_cover_image(playlist_id)

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

Get cover image of a playlist.

```APIDOC
## playlist_cover_image(playlist_id)

### Description
Get cover image of a playlist.

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

```

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

### Spotify.current_user_playlist_create()

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

Creates a new playlist for the current user.

```APIDOC
## current_user_playlist_create()

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

### Method
current_user_playlist_create()

### Parameters
None documented.

### Response
Returns the created playlist.
```

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

### SpotifyStateError.__init__

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

Constructor for the SpotifyStateError exception, which is raised when the OAuth state sent and received differ. It accepts optional local and remote state values, a message, error details, and additional arguments.

```APIDOC
## SpotifyStateError.__init__

### Description
Constructor for the SpotifyStateError exception, which is raised when the OAuth state sent and received differ. It accepts optional local and remote state values, a message, error details, and additional arguments.

### Method
Constructor

### Parameters
- **local_state** (optional) - The state value sent by the client.
- **remote_state** (optional) - The state value received from the server.
- **message** (optional) - Custom error message.
- **error** (optional) - Error code or identifier.
- **error_description** (optional) - Human-readable error description.
- **args** - Additional positional arguments.
- **kwargs** - Additional keyword arguments.

```

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

### SpotifyOAuth.get_access_token

Source: https://spotipy.readthedocs.io/en/latest/

Gets the access token for the app given the code.

```APIDOC
## SpotifyOAuth.get_access_token

### Description
Gets the access token for the app given the code.

### Method
Function

### Parameters
- **code** (string) - Optional - The response code.
- **as_dict** (bool) - Optional (deprecated) - A boolean indicating if returning the access token as a token_info dictionary, otherwise it will be returned as a string.
- **check_cache** (bool) - Optional - Whether to check the cache for a token.

### Response
Returns the access token as a token_info dictionary or a string.
```

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

### SpotifyImplicitGrant.__init__

Source: https://spotipy.readthedocs.io/en/latest/

Creates an Auth Manager using the Implicit Grant flow. Accepts client ID, redirect URI, state, scope, cache handler, and other optional parameters.

```APIDOC
## SpotifyImplicitGrant.__init__

### Description
Creates an Auth Manager using the Implicit Grant flow. See help(SpotifyImplicitGrant) for full Security Warning.

### Method
Constructor

### Signature
__init__(client_id=None, redirect_uri=None, state=None, scope=None, cache_path=None, username=None, show_dialog=False, cache_handler=None)

### 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 - May be supplied, no verification is performed.
- **scope** (list or string) - Optional - Either a list of scopes or comma separated string of scopes. e.g, "playlist-read-private,playlist-read-collaborative".
- **cache_handler** (CacheHandler) - Optional - An instance of the CacheHandler class to handle getting and saving cached authorization tokens. May be supplied, will otherwise use CacheFileHandler. (takes precedence over cache_path and username)
- **cache_path** (string) - Optional - Deprecated. May be supplied, will otherwise be generated (takes precedence over username).
- **username** (string) - Optional - Deprecated. May be supplied or set as environment variable (will set cache_path to .cache-{username}).
- **show_dialog** (boolean) - Optional - Interpreted as boolean.

### Response
No return value.
```

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

### SpotifyOAuth.__init__

Source: https://spotipy.readthedocs.io/en/latest/

Implements Authorization Code Flow for Spotify's OAuth implementation. Accepts client credentials, redirect URI, scope, cache handler, and other optional parameters.

```APIDOC
## SpotifyOAuth.__init__

### Description
Implements Authorization Code Flow for Spotify's OAuth implementation.

### Method
Constructor

### Signature
__init__(client_id=None, client_secret=None, redirect_uri=None, state=None, scope=None, cache_path=None, username=None, proxies=None, show_dialog=False, requests_session=True, requests_timeout=None, open_browser=True, cache_handler=None)

### Parameters
- **client_id** (string) - Required - Must be supplied or set as environment variable.
- **client_secret** (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 - May be supplied.
- **scope** (list or string) - Optional - Either a list of scopes or comma separated string of scopes.
- **cache_path** (string) - Optional - May be supplied, will otherwise be generated.
- **username** (string) - Optional - May be supplied or set as environment variable.
- **proxies** (dict) - Optional - Proxy settings.
- **show_dialog** (boolean) - Optional - Interpreted as boolean.
- **requests_session** (boolean) - Optional - Whether to use a requests session.
- **requests_timeout** (number) - Optional - Timeout for requests.
- **open_browser** (boolean) - Optional - Whether to open the browser for authorization.
- **cache_handler** (CacheHandler) - Optional - An instance of the CacheHandler class.

### Response
No return value.
```

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

### user_playlists(user, limit=50, offset=0)

Source: https://spotipy.readthedocs.io/en/latest/

Gets playlists of a user.

```APIDOC
## user_playlists(user, limit=50, offset=0)

### Description
Gets playlists of a user.

### Parameters
- **user** (string) - Required - The id of the user.
- **limit** (int) - Optional - The number of items to return. Default: 50.
- **offset** (int) - Optional - The index of the first item to return. Default: 0.

```

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

### Set Spotify environment variables

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

Set the required environment variables for Spotipy: SPOTIPY_CLIENT_ID, SPOTIPY_CLIENT_SECRET, and SPOTIPY_REDIRECT_URI. On Windows, use $env:"credentials" instead of export.

```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'
```

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

### playlist_items

Source: https://spotipy.readthedocs.io/en/latest/

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

```APIDOC
## playlist_items

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

### Method
GET

### Endpoint
Not specified

### 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** (tuple) - Optional - List of item types to return. Valid types are: track and episode. Default: ('track', 'episode')

### Response
Not specified
```

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

### user_playlists(user, limit=50, offset=0)

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

Gets playlists of a user.

```APIDOC
## user_playlists(user, limit=50, offset=0)

### Description
Gets playlists of a user.

### Method
Function call

### Parameters
- **user** (string) - Required - The id of the user.
- **limit** (integer) - Optional - The number of items to return (default: 50).
- **offset** (integer) - Optional - The index of the first item to return (default: 0).

### Response
No return value documented.
```

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

### SpotifyClientCredentials.__init__

Source: https://spotipy.readthedocs.io/en/latest/

Creates a Client Credentials Flow Manager for server-to-server authentication. This flow does not require user interaction and only allows access to endpoints that do not access user information.

```APIDOC
## SpotifyClientCredentials.__init__

### Description
Creates a Client Credentials Flow Manager for server-to-server authentication. This flow does not require user interaction and only allows access to endpoints that do not access user information.

### Method
Constructor

### Parameters
- **client_id** (string) - Optional - Must be supplied or set as environment variable SPOTIPY_CLIENT_ID
- **client_secret** (string) - Optional - Must be supplied or set as environment variable SPOTIPY_CLIENT_SECRET
- **proxies** (object) - Optional - Proxy for the requests library to route through
- **requests_session** (object) - Optional - A Requests session
- **requests_timeout** (number) - Optional - Tell Requests to stop waiting for a response after a given number of seconds
- **cache_handler** (CacheHandler) - Optional - An instance of the CacheHandler class to handle getting and saving cached authorization tokens. Takes precedence over cache_path and username.

### Notes
- The Client Credentials flow is used for server-to-server authentication.
- Only endpoints that do not access user information can be accessed.
- Endpoints that require authorization scopes cannot be accessed.
- The advantage is that it does not require any user interaction.
```

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

### SpotifyPKCE.get_pkce_handshake_parameters

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

Generates the parameters needed for the PKCE handshake.

```APIDOC
## SpotifyPKCE.get_pkce_handshake_parameters

### Description
Generates the parameters needed for the PKCE handshake.

### Method
Method

### Signature
`get_pkce_handshake_parameters()`
```

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

### recommendation_genre_seeds

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

Get a list of genres available for the recommendations function.

```APIDOC
## recommendation_genre_seeds()

### Description
Get a list of genres available for the recommendations function.
```

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

### spotipy.oauth2.SpotifyOauthError.__init__

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

Constructor for the SpotifyOauthError class.

```APIDOC
## spotipy.oauth2.SpotifyOauthError.__init__

### Description
Initializes a SpotifyOauthError instance.

### Method
Constructor

### Signature
`SpotifyOauthError.__init__(self, ...)`

### Parameters
No parameters are explicitly documented in the source.

### Response
No return value is documented.
```

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

### playlist_items

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

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

```APIDOC
## playlist_items(playlist_id, fields=None, limit=50, offset=0, market=None, additional_types=('track', 'episode'))

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

### Parameters
- **playlist_id** - the playlist ID, URI or URL
- **fields** - which fields to return
- **limit** - the maximum number of tracks to return
- **offset** - the index of the first track to return
- **market** - an ISO 3166-1 alpha-2 country code.
- **additional_types** - list of item types to return. valid types are: track and episode
```

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

### SpotifyClientCredentials constructor

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

Creates a Client Credentials Flow Manager for server-to-server authentication. Requires client_id and client_secret, either passed directly or set as environment variables.

```APIDOC
## SpotifyClientCredentials.__init__

### Description
Creates a Client Credentials Flow Manager. This flow is used for server-to-server authentication and does not require user interaction. Only endpoints that do not access user information can be accessed.

### Parameters
- **client_id** (string) - Optional - Must be supplied or set as environment variable SPOTIPY_CLIENT_ID.
- **client_secret** (string) - Optional - Must be supplied or set as environment variable SPOTIPY_CLIENT_SECRET.
- **proxies** (dict) - Optional - Proxy configuration for the requests library.
- **requests_session** (requests.Session) - Optional - A Requests session.
- **requests_timeout** (number) - Optional - Timeout in seconds for requests.
- **cache_handler** (CacheHandler) - Optional - An instance of CacheHandler to handle caching of authorization tokens. Defaults to CacheFileHandler.

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

auth_manager = SpotifyClientCredentials(client_id='your_client_id', client_secret='your_client_secret')
```
```

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

### current_playback

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

Get information about the user's current playback.

```APIDOC
## current_playback

### Description
Get information about user’s current playback.

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

```

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

### show(show_id, market=None)

Source: https://spotipy.readthedocs.io/en/latest/

Returns a single show given the show's ID, URI, or URL. Optionally specify a market for availability.

```APIDOC
## show(show_id, market=None)

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

### Method
N/A (SDK method)

### Parameters
- **show_id** (string) - Required - the show ID, URI or URL
- **market** (string) - Optional - an ISO 3166-1 alpha-2 country code. The show must be available in the given market. If user-based authorization is in use, the user's country takes precedence. If neither market nor user country are provided, the content is considered unavailable for the client.

```

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

### new_releases

Source: https://spotipy.readthedocs.io/en/latest/

Get a list of new album releases featured in Spotify.

```APIDOC
## new_releases

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

### Method
GET

### Endpoint
Not specified

### 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. Minimum: 1. Maximum: 50.
- **offset** (integer) - Optional - The index of the first item to return. Default: 0.

### Response
Not specified
```

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

### SpotifyImplicitGrant.__init__

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

Creates an Auth Manager using the Implicit Grant flow. This constructor initializes the manager with client credentials, redirect URI, scope, and cache handling options.

```APIDOC
## SpotifyImplicitGrant.__init__

### Description
Creates Auth Manager using the Implicit Grant flow. See help(SpotifyImplicitGrant) for full Security Warning.

### Method
Constructor

### 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 - May be supplied, no verification is performed
- **scope** (list or string) - Optional - Either a list of scopes or comma separated string of scopes. e.g, "playlist-read-private,playlist-read-collaborative"
- **cache_handler** (CacheHandler) - Optional - An instance of the CacheHandler class to handle getting and saving cached authorization tokens. May be supplied, will otherwise use CacheFileHandler. (takes precedence over cache_path and username)
- **cache_path** (string) - Optional - (deprecated) May be supplied, will otherwise be generated (takes precedence over username)
- **username** (string) - Optional - (deprecated) May be supplied or set as environment variable (will set cache_path to .cache-{username})
- **show_dialog** (boolean) - Optional - Interpreted as boolean
```

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

### get_audiobook_chapters

Source: https://spotipy.readthedocs.io/en/latest/

Get Spotify catalog information about an audiobook's chapters.

```APIDOC
## get_audiobook_chapters

### Description
Get Spotify catalog information about an audiobook's chapters.

### Method
GET

### Endpoint
Not specified

### Parameters
#### Path Parameters
- **id** (string) - Required - The Spotify ID for the audiobook

#### Query Parameters
- **market** (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.

### Response
Not specified
```
Tokens:
Raw