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, useAccept-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, 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.
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
- 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
- get_chart()¶
Get overall charts for tracks, albums, artists and playlists.
Combine charts of several resources in one endpoint.
- Returns
a
Chart
instance.- Return type
- get_tracks_chart()¶
Get top tracks.
- Returns
a list of
Track
instances.- Return type
list[deezer.resources.Track]
- get_albums_chart()¶
Get top albums.
- Returns
a list of
Album
instances.- Return type
list[deezer.resources.Album]
- get_artists_chart()¶
Get top artists.
- Returns
a list of
Artist
instances.- Return type
list[deezer.resources.Artist]
- get_podcasts_chart()¶
Get top podcasts.
- 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
- list_editorials()¶
List editorials.
- Returns
a
PaginatedList
ofEditorial
objects.- Return type
- get_episode(episode_id)¶
Get the episode with the given ID.
- Returns
a
Episode
object- Parameters
episode_id (int) –
- Return type
- get_genre(genre_id)¶
Get the genre with the given ID
- Returns
a
Genre
object- Parameters
genre_id (int) –
- Return type
- list_genres()¶
List musical genres.
- Returns
a
PaginatedList
ofGenre
objects.- Return type
- get_playlist(playlist_id)¶
Get the playlist with the given ID.
- Returns
a
Playlist
object- Parameters
playlist_id (int) –
- Return type
- get_podcast(podcast_id)¶
Get the podcast with the given ID.
- Returns
a
Podcast
object- Parameters
podcast_id (int) –
- Return type
- get_radio(radio_id)¶
Get the radio with the given ID.
- Returns
a
Radio
object- Parameters
radio_id (int) –
- Return type
- list_radios()¶
List radios.
- Returns
a
PaginatedList
ofRadio
objects.- Return type
- get_radios_top()¶
Get the top radios.
- Returns
a
PaginatedList
ofRadio
objects.- Return type
- get_track(track_id)¶
Get the track with the given ID.
- Returns
a
Track
object- Parameters
track_id (int) –
- Return type
- get_user(user_id=None)¶
Get the user with the given ID.
- 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
- 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
ofArtist
instances.- Return type
- 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
ofTrack
instances.- Return type
- 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
ofTrack
instances.- Return type
- 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
- 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