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.

add_user_album(album_id: int) → bool¶

Add an album to the user’s library

Parameters: album_id – the ID of the album to add.
Returns: boolean whether the operation succeeded.

add_user_artist(artist_id: int) → bool¶

Add an artist to the user’s library

Parameters: artist_id – the ID of the artist to add.
Returns: boolean whether the operation succeeded.

add_user_track(track_id: int) → bool¶

Add a track to the user’s library

Parameters: track_id – the ID of the track to add.
Returns: boolean whether the operation succeeded.

get_album(album_id: int) → deezer.resources.Album¶

Get the album with the given ID.

Returns: an Album object

get_albums_chart() → List[deezer.resources.Album]¶

Get top albums.

Returns: a list of Album instances.

get_artist(artist_id: int) → deezer.resources.Artist¶

Get the artist with the given ID.

Returns: an Artist object

get_artists_chart() → List[deezer.resources.Artist]¶

Get top artists.

Returns: a list of Artist instances.

get_chart() → deezer.resources.Chart¶

Get overall charts for tracks, albums, artists and playlists.

Combines charts of several resources in one endpoint.

Returns: a Chart instance.

get_episode(episode_id: int) → deezer.resources.Episode¶

Get the episode with the given ID.

Returns: a Episode object

get_genre(genre_id: int) → deezer.resources.Genre¶

Get the genre with the given ID

Returns: a Genre object

get_playlist(playlist_id: int) → deezer.resources.Playlist¶

Get the playlist with the given ID.

Returns: a Playlist object

get_playlists_chart() → List[deezer.resources.Playlist]¶

Get top playlists.

Returns: a list of Playlist instances.

get_podcast(podcast_id: int) → deezer.resources.Podcast¶

Get the podcast with the given ID.

Returns: a Podcast object

get_podcasts_chart() → List[deezer.resources.Podcast]¶

Get top podcasts.

Returns: a list of Podcasts instances.

get_radio(radio_id: int) → deezer.resources.Radio¶

Get the radio with the given ID..

Returns: a Radio object

get_radios_top()¶

Get the top radios (5 radios).

Returns: a Radio object

get_track(track_id: int) → deezer.resources.Track¶

Get the track with the given ID.

Returns: a Track object

get_tracks_chart() → List[deezer.resources.Track]¶

Get top tracks.

Returns: a list of Track instances.

get_user(user_id: Optional[int] = None) → deezer.resources.User¶

Get the user with the given ID.

Returns: a User object

get_user_albums(user_id: Optional[int] = None) → List[deezer.resources.Album]¶

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

Parameters: user_id – the user ID to get favourites albums.
Returns: a list of Album instances.

get_user_artists(user_id: Optional[int] = None) → List[deezer.resources.Artist]¶

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

Parameters: user_id – the user ID to get favourites artists.
Returns: a list of Artist instances.

get_user_history() → List[deezer.resources.Track]¶

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

Returns: a list of Track instances.

get_user_tracks(user_id: Optional[int] = None) → List[deezer.resources.Track]¶

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

Parameters: user_id – the user ID to get favourites tracks.
Returns: a list of Track instances.

list_genres() → List[deezer.resources.Genre]¶

List musical genres.

Returns: a list of Genre objects.

list_radios() → List[deezer.resources.Radio]¶

List radios.

Returns: a list of Radio objects

rate_album(album_id: int, note: int) → bool¶

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

remove_user_album(album_id: int) → bool¶

Remove an album from the user’s library

Parameters: album_id – the ID of the album to remove.
Returns: boolean whether the operation succeeded.

remove_user_artist(artist_id: int) → bool¶

Remove an artist from the user’s library

Parameters: artist_id – the ID of the artist to remove.
Returns: boolean whether the operation succeeded.

remove_user_track(track_id: int) → bool¶

Remove a track from the user’s library

Parameters: track_id – the ID of the track to remove.
Returns: boolean whether the operation succeeded.

request(method: str, path: str, parent: Optional[deezer.resources.Resource] = None, resource_type: Optional[Type[deezer.resources.Resource]] = None, **params)¶

Make a request to the API and parse the response.

Parameters

method – HTTP verb to use: GET, POST< DELETE, …
path – The path to make the API call to (e.g. ‘artist/1234’).
parent – A reference to the parent resource, to avoid fetching again.
resource_type – The resource class to use as top level.
params – Query parameters to add the the request

search(query: str = '', strict: Optional[bool] = None, ordering: Optional[str] = None, artist: Optional[str] = None, album: Optional[str] = None, track: Optional[str] = None, label: Optional[str] = None, dur_min: Optional[int] = None, dur_max: Optional[int] = None, bpm_min: Optional[int] = None, bpm_max: Optional[int] = None, index: Optional[int] = None, limit: Optional[int] = None)¶

Search tracks.

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

Parameters

query – the query to search for, this is directly passed as q query.
strict – whether to disable fuzzy search and enable strict mode.
ordering – see Deezer’s API docs for possible values.
artist – parameter for the advanced search feature.
album – parameter for the advanced search feature.
track – parameter for the advanced search feature.
label – parameter for the advanced search feature.
dur_min – parameter for the advanced search feature.
dur_max – parameter for the advanced search feature.
bpm_min – parameter for the advanced search feature.
bpm_max – parameter for the advanced search feature.
index – the offset of the first object you want to get.
limit – the maximum number of objects to return.

Returns

a list of Track instances.

search_albums(query: str = '', strict: Optional[bool] = None, ordering: Optional[str] = None, index: Optional[int] = None, limit: Optional[int] = None) → List[deezer.resources.Album]¶

Search albums matching the given query.

Parameters

query – the query to search for, this is directly passed as q query.
strict – whether to disable fuzzy search and enable strict mode.
ordering – see Deezer’s API docs for possible values.
index – the offset of the first object you want to get.
limit – the maximum number of objects to return.

Returns

list of Album instances.

search_artists(query: str = '', strict: Optional[bool] = None, ordering: Optional[str] = None, index: Optional[int] = None, limit: Optional[int] = None) → List[deezer.resources.Artist]¶

Search artists matching the given query.

Parameters

query – the query to search for, this is directly passed as q query.
strict – whether to disable fuzzy search and enable strict mode.
ordering – see Deezer’s API docs for possible values.
index – the offset of the first object you want to get.
limit – the maximum number of objects to return.

Returns

list of Album instances.