Skip to main content

​
SpotifyClient

The SpotifyClient class is the main synchronous client for interacting with the Spotify Web API. It provides access to all Spotify API services through dedicated service attributes.

​
Constructor

SpotifyClient(
    access_token: str | None = None,
    *,
    client_id: str | None = None,
    client_secret: str | None = None,
    auth_provider: AuthProvider | None = None,
    timeout: float = 30.0,
    max_retries: int = 3,
)
Initialize a new Spotify client instance.

​
Parameters

​
access_token
str | None
default:"None"
Spotify API access token. Use this if you already have a valid access token.
​
client_id
str | None
default:"None"
Spotify API client ID. Use with client_secret for client credentials flow.
​
client_secret
str | None
default:"None"
Spotify API client secret. Use with client_id for client credentials flow.
​
auth_provider
AuthProvider | None
default:"None"
Custom auth provider for dynamic access token management. Provide this for advanced authentication scenarios.
​
timeout
float
default:"30.0"
Default request timeout in seconds. Controls how long to wait for API responses.
​
max_retries
int
default:"3"
Maximum number of retries for failed requests. The client will automatically retry failed requests up to this limit.
You must provide exactly one of the following:
  • access_token
  • Both client_id and client_secret
  • auth_provider
Providing multiple authentication methods will raise a ValueError.

​
Examples

from spotify_sdk import SpotifyClient

client = SpotifyClient(access_token="your_access_token")

​
Service Attributes

The SpotifyClient provides access to all Spotify API services through the following attributes:
​
albums
AlbumService
Service for interacting with album endpoints. Get album details, tracks, and more.
​
artists
ArtistService
Service for interacting with artist endpoints. Get artist details, albums, top tracks, and related artists.
​
audiobooks
AudiobookService
Service for interacting with audiobook endpoints. Get audiobook details and chapters.
​
chapters
ChapterService
Service for interacting with audiobook chapter endpoints. Get chapter details.
​
episodes
EpisodeService
Service for interacting with podcast episode endpoints. Get episode details.
​
library
LibraryService
Service for managing the user’s library. Save and retrieve albums, tracks, audiobooks, episodes, and shows.
​
playlists
PlaylistService
Service for managing playlists. Create, update, and retrieve playlists and their items.
​
search
SearchService
Service for searching Spotify content. Search for albums, artists, playlists, tracks, shows, episodes, and audiobooks.
​
shows
ShowService
Service for interacting with podcast show endpoints. Get show details and episodes.
​
tracks
TrackService
Service for interacting with track endpoints. Get track details, audio features, and audio analysis.
​
users
UserService
Service for interacting with user endpoints. Get user profiles and manage following.

​
Class Methods

​
from_client_credentials

@classmethod
SpotifyClient.from_client_credentials(
    *,
    client_id: str | None = None,
    client_secret: str | None = None,
    timeout: float = 30.0,
    max_retries: int = 3,
) -> SpotifyClient
Create a client using the client credentials flow. This is a convenience method for creating a client with client credentials authentication.

​
Parameters

​
client_id
str | None
default:"None"
Spotify API client ID.
​
client_secret
str | None
default:"None"
Spotify API client secret.
​
timeout
float
default:"30.0"
Default request timeout in seconds.
​
max_retries
int
default:"3"
Maximum number of retries for failed requests.

​
Returns

A new SpotifyClient instance configured with client credentials authentication.

​
Example

from spotify_sdk import SpotifyClient

client = SpotifyClient.from_client_credentials(
    client_id="your_client_id",
    client_secret="your_client_secret"
)

​
Instance Methods

​
close

def close() -> None
Close the client and release resources. This method should be called when you’re done using the client to properly clean up network connections and other resources.

​
Example

from spotify_sdk import SpotifyClient

client = SpotifyClient(access_token="your_access_token")
try:
    album = client.albums.get("3RlHPKEsbd6W01sIPC5k8v")
    print(album.name)
finally:
    client.close()

​
Context Manager Support

The SpotifyClient supports the context manager protocol, allowing you to use it with Python’s with statement. The client will automatically close when the context exits.

​
Example

from spotify_sdk import SpotifyClient

with SpotifyClient(access_token="your_access_token") as client:
    # Client is automatically closed when the block exits
    album = client.albums.get("3RlHPKEsbd6W01sIPC5k8v")
    tracks = client.tracks.get(["track_id_1", "track_id_2"])
    results = client.search.search("Bohemian Rhapsody", types=["track"])

​
Usage Examples

from spotify_sdk import SpotifyClient

with SpotifyClient(access_token="your_access_token") as client:
    album = client.albums.get("3RlHPKEsbd6W01sIPC5k8v")
    print(f"Album: {album.name}")
    print(f"Artist: {album.artists[0].name}")
    print(f"Release Date: {album.release_date}")

Build docs developers (and LLMs) love

Get started for freeTalk to us