Client module¶

Implements a client class to query the Deezer API

class deezer.client.Client(app_id=None, app_secret=None, access_token=None, headers=None, **kwargs)¶

A client to retrieve some basic infos about Deezer resourses.

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

>>> import deezer
>>> client = deezer.Client(app_id='foo', app_secret='bar')

This client provides several method to retrieve the content of most sort 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

app_id – application ID.
app_secret – application secret.
access_token – user access token.
headers – a dictionary of headers to be used.

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

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.
params – Query parameters to add to the request

get_album(album_id)¶

Get the album with the given ID.

Returns: an Album object
Parameters: album_id (int) –
Return type: deezer.resources.Album

rate_album(album_id, note)¶

Rate the album of the given ID with the given note.

The note should be and integer between 1 and 5.

Returns

boolean whether rating was applied

Parameters

album_id (int) –
note (int) –

Return type

bool

get_artist(artist_id)¶

Get the artist with the given ID.

Returns: an Artist object
Parameters: artist_id (int) –
Return type: deezer.resources.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: deezer.resources.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[deezer.resources.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[deezer.resources.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[deezer.resources.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[deezer.resources.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[deezer.resources.Podcast]

get_editorial(editorial_id)¶

Get the editorial with the given ID.

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

list_editorials()¶

List editorials.

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

get_episode(episode_id)¶

Get the episode with the given ID.

Returns: a Episode object
Parameters: episode_id (int) –
Return type: deezer.resources.Episode

get_genre(genre_id)¶

Get the genre with the given ID

Returns: a Genre object
Parameters: genre_id (int) –
Return type: deezer.resources.Genre

list_genres()¶

List musical genres.

Returns: a list of Genre instances
Return type: list[deezer.resources.Genre]

get_playlist(playlist_id)¶

Get the playlist with the given ID.

Returns: a Playlist object
Parameters: playlist_id (int) –
Return type: deezer.resources.Playlist

get_podcast(podcast_id)¶

Get the podcast with the given ID.

Returns: a Podcast object
Parameters: podcast_id (int) –
Return type: deezer.resources.Podcast

get_radio(radio_id)¶

Get the radio with the given ID.

Returns: a Radio object
Parameters: radio_id (int) –
Return type: deezer.resources.Radio

list_radios()¶

List radios.

Returns: a list of Radio instances
Return type: list[deezer.resources.Radio]

get_radios_top()¶

Get the top radios.

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

get_track(track_id)¶

Get the track with the given ID.

Returns: a Track object
Parameters: track_id (int) –
Return type: deezer.resources.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_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 list of Album instances.
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_history()¶

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

Returns: a PaginatedList of Track instances.
Return type: deezer.pagination.PaginatedList[deezer.resources.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

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]