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.
- 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_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.