Client¶

The client class is the main entry point to start querying the Deezer API

class deezer.Client(access_token=None, headers=None)¶

A client to retrieve some basic infos about Deezer resources.

Create a client instance with the given options. Options should be passed in to the constructor as kwargs.

>>> import deezer
>>> client = deezer.Client()

This client provides several methods to retrieve the content most kinds of Deezer objects, based on their json structure.

Headers can be forced by using the headers kwarg. For example, use Accept-Language header to force the output language.

>>> import deezer
>>> client = deezer.Client(headers={'Accept-Language': 'fr'})

Parameters:

access_token (str | None) – user access token.
headers (HeaderTypes | None) – a dictionary of headers to be used.

request(method, path, parent=None, resource_type=None, resource_id=None, paginate_list=False, **kwargs)¶

Make a request to the API and parse the response.

Parameters:

method (str) – HTTP verb to use: GET, POST< DELETE, …
path (str) – The path to make the API call to (e.g. ‘artist/1234’).
parent (Resource | None) – A reference to the parent resource, to avoid fetching again.
resource_type (type[Resource] | None) – The resource class to use as top level.
resource_id (int | None) – The resource id to use as top level.
paginate_list – Whether to wrap list into a pagination object.

get_album(album_id)¶

Get the album with the given ID.

Returns:: an Album object
Parameters:: album_id (int)
Return type:: Album

get_artist(artist_id)¶

Get the artist with the given ID.

Returns:: an Artist object
Parameters:: artist_id (int)
Return type:: Artist

get_chart(genre_id=0)¶

Get overall charts for tracks, albums, artists and playlists for the given genre ID.

Combine charts of several resources in one endpoint.

Parameters:: genre_id (int) – the genre ID, default to All genre (genre_id = 0).
Returns:: a Chart instance.
Return type:: Chart

get_tracks_chart(genre_id=0)¶

Get top tracks for the given genre ID.

Parameters:: genre_id (int) – the genre ID, default to All genre (genre_id = 0).
Returns:: a list of Track instances.
Return type:: list[Track]

get_albums_chart(genre_id=0)¶

Get top albums for the given genre ID.

Parameters:: genre_id (int) – the genre ID, default to All genre (genre_id = 0).
Returns:: a list of Album instances.
Return type:: list[Album]

get_artists_chart(genre_id=0)¶

Get top artists for the given genre ID.

Parameters:: genre_id (int) – the genre ID, default to All genre (genre_id = 0).
Returns:: a list of Artist instances.
Return type:: list[Artist]

get_playlists_chart(genre_id=0)¶

Get top playlists for the given genre ID.

Parameters:: genre_id (int) – the genre ID, default to All genre (genre_id = 0).
Returns:: a list of Playlist instances.
Return type:: list[Playlist]

get_podcasts_chart(genre_id=0)¶

Get top podcasts for the given genre ID.

Parameters:: genre_id (int) – the genre ID, default to All genre (genre_id = 0).
Returns:: a list of Podcast instances.
Return type:: list[Podcast]

get_editorial(editorial_id)¶

Get the editorial with the given ID.

Returns:: a Editorial object.
Parameters:: editorial_id (int)
Return type:: Editorial

list_editorials()¶

List editorials.

Returns:: a PaginatedList of Editorial objects.
Return type:: PaginatedList[Editorial]

get_episode(episode_id)¶

Get the episode with the given ID.

Returns:: a Episode object
Parameters:: episode_id (int)
Return type:: Episode

get_genre(genre_id)¶

Get the genre with the given ID.

Returns:: a Genre object
Parameters:: genre_id (int)
Return type:: Genre

list_genres()¶

List musical genres.

Returns:: a list of Genre instances
Return type:: list[Genre]

get_playlist(playlist_id)¶

Get the playlist with the given ID.

Returns:: a Playlist object
Parameters:: playlist_id (int)
Return type:: Playlist

get_podcast(podcast_id)¶

Get the podcast with the given ID.

Returns:: a Podcast object
Parameters:: podcast_id (int)
Return type:: Podcast

get_radio(radio_id)¶

Get the radio with the given ID.

Returns:: a Radio object
Parameters:: radio_id (int)
Return type:: Radio

list_radios()¶

List radios.

Returns:: a list of Radio instances
Return type:: list[Radio]

get_radios_top()¶

Get the top radios.

Returns:: a PaginatedList of Radio objects.
Return type:: PaginatedList[Radio]

get_track(track_id)¶

Get the track with the given ID.

Returns:: a Track object
Parameters:: track_id (int)
Return type:: Track

get_user(user_id=None)¶

Get the user with the given ID.

Returns:: a User object
Parameters:: user_id (int | None)
Return type:: User

get_user_recommended_tracks(**kwargs)¶

Get user’s recommended tracks.

Returns:: a PaginatedList of Track instances
Return type:: PaginatedList[Track]

get_user_recommended_albums(**kwargs)¶

Get user’s recommended albums.

Returns:: a PaginatedList of Track instances
Return type:: PaginatedList[Album]

get_user_recommended_artists(**kwargs)¶

Get user’s recommended artists.

Returns:: a PaginatedList of Track instances
Return type:: PaginatedList[Artist]

get_user_recommended_playlists(**kwargs)¶

Get user’s recommended playlist.

Returns:: a PaginatedList of Track instances
Return type:: PaginatedList[Playlist]

get_user_flow(**kwargs)¶

Get user’s flow.

Returns:: a PaginatedList of Track instances
Return type:: PaginatedList[Track]

get_user_albums(user_id=None)¶

Get the favourites albums for the given user_id if provided or current user if not.

Parameters:: user_id (int | None) – the user ID to get favourites albums.
Returns:: a PaginatedList of Album objects.
Return type:: PaginatedList[Album]

add_user_album(album_id)¶

Add an album to the user’s library.

Parameters:: album_id (int) – the ID of the album to add.
Returns:: boolean whether the operation succeeded.
Return type:: bool

remove_user_album(album_id)¶

Remove an album from the user’s library.

Parameters:: album_id (int) – the ID of the album to remove.
Returns:: boolean whether the operation succeeded.
Return type:: bool

get_user_artists(user_id=None)¶

Get the favourites artists for the given user_id if provided or current user if not.

Parameters:: user_id (int | None) – the user ID to get favourites artists.
Returns:: a PaginatedList of Artist instances.
Return type:: PaginatedList[Artist]

add_user_artist(artist_id)¶

Add an artist to the user’s library.

Parameters:: artist_id (int) – the ID of the artist to add.
Returns:: boolean whether the operation succeeded.
Return type:: bool

remove_user_artist(artist_id)¶

Remove an artist from the user’s library.

Parameters:: artist_id (int) – the ID of the artist to remove.
Returns:: boolean whether the operation succeeded.
Return type:: bool

get_user_followers(user_id=None)¶

Get the followers for the given user_id if provided or current user if not.

Parameters:: user_id (int | None) – the user ID to get followers.
Returns:: a PaginatedList of User instances.
Return type:: PaginatedList[User]

get_user_followings(user_id=None)¶

Get the followings for the given user_id if provided or current user if not.

Parameters:: user_id (int | None) – the user ID to get followings.
Returns:: a PaginatedList of User instances.
Return type:: PaginatedList[User]

add_user_following(user_id)¶

Follow the given user ID as the currently authenticated user.

Parameters:: user_id (int) – the ID of the user to follow.
Returns:: boolean whether the operation succeeded.
Return type:: bool

remove_user_following(user_id)¶

Stop following the given user ID as the currently authenticated user.

Parameters:: user_id (int) – the ID of the user to stop following.
Returns:: boolean whether the operation succeeded.
Return type:: bool

get_user_history()¶

Returns a list of the recently played tracks for the current user.

Returns:: a PaginatedList of Track instances.
Return type:: PaginatedList[Track]

get_user_tracks(user_id=None)¶

Get the favourites tracks for the given user_id if provided or current user if not.

Parameters:: user_id (int | None) – the user ID to get favourites tracks.
Returns:: a PaginatedList of Track instances.
Return type:: PaginatedList[Track]

add_user_track(track_id)¶

Add a track to the user’s library.

Parameters:: track_id (int) – the ID of the track to add.
Returns:: boolean whether the operation succeeded.
Return type:: bool

remove_user_track(track_id)¶

Remove a track from the user’s library.

Parameters:: track_id (int) – the ID of the track to remove.
Returns:: boolean whether the operation succeeded.
Return type:: bool

remove_user_playlist(playlist_id)¶

Remove a playlist from the user’s library.

Parameters:: playlist_id (int) – the ID of the playlist to remove.
Returns:: boolean whether the operation succeeded.
Return type:: bool

add_user_playlist(playlist_id)¶

Add a playlist to the user’s library.

Parameters:: playlist_id (int) – the ID of the playlist to add.
Returns:: boolean whether the operation succeeded.
Return type:: bool

create_playlist(playlist_name)¶

Create a playlist on the user’s account.

Parameters:: playlist_name – the name of the playlist.
Returns:: the ID of the playlist that was created
Return type:: int

delete_playlist(playlist_id)¶

Delete a playlist from the user’s account.

Parameters:: playlist_id – the ID of the playlist to remove.
Returns:: boolean whether the operation succeeded.
Return type:: bool

search(query='', strict=None, ordering=None, artist=None, album=None, track=None, label=None, dur_min=None, dur_max=None, bpm_min=None, bpm_max=None)¶

Search tracks.

Advanced search is available by either formatting the query yourself or by using the dedicated keywords arguments.

Parameters:

query (str) – the query to search for, this is directly passed as q query.
strict (bool | None) – whether to disable fuzzy search and enable strict mode.
ordering (str | None) – see Deezer API docs for possible values.
artist (str | None) – parameter for the advanced search feature.
album (str | None) – parameter for the advanced search feature.
track (str | None) – parameter for the advanced search feature.
label (str | None) – parameter for the advanced search feature.
dur_min (int | None) – parameter for the advanced search feature.
dur_max (int | None) – parameter for the advanced search feature.
bpm_min (int | None) – parameter for the advanced search feature.
bpm_max (int | None) – parameter for the advanced search feature.

Returns:

a list of Track instances.

search_albums(query='', strict=None, ordering=None)¶

Search albums matching the given query.

Parameters:

query (str) – the query to search for, this is directly passed as q query.
strict (bool | None) – whether to disable fuzzy search and enable strict mode.
ordering (str | None) – see Deezer API docs for possible values.

Returns:

list of Album instances.

Return type:

PaginatedList[Album]

search_artists(query='', strict=None, ordering=None)¶

Search artists matching the given query.

Parameters:

query (str) – the query to search for, this is directly passed as q query.
strict (bool | None) – whether to disable fuzzy search and enable strict mode.
ordering (str | None) – see Deezer API docs for possible values.

Returns:

list of Album instances.

Return type:

PaginatedList[Artist]

search_playlists(query='', strict=None, ordering=None)¶

Search playlists matching the given query.

Parameters:

query (str) – the query to search for, this is directly passed as q query.
strict (bool | None) – whether to disable fuzzy search and enable strict mode.
ordering (str | None) – see Deezer API docs for possible values.

Returns:

list of Playlist instances.

Return type:

PaginatedList[Playlist]