Usage

First steps

To start calling the API, you first need to instantiate a Client:

>>> client = deezer.Client()

From there, you can search for some terms:

>>> client.search('Daft Punk')
[<Track: Daft Punk>,
<Track: Daft Punk>,
<Track: One More Time>,
<Track: Around the World>,
<Track: Harder, Better, Faster, Stronger>,
<Track: Da Funk>,
<Track: Veridis Quo>,
<Track: Aerodynamic>,
<Track: Something About Us>,
<Track: Giorgio by Moroder>,
<Track: Give Life Back to Music>,
<Track: Within>,
<Track: Daft Punk>,
<Track: Digital Love>,
<Track: Nightvision>,
<Track: The Game of Love>,
<Track: Around the World / Harder, Better, Faster, Stronger>,
<Track: Beyond>,
<Track: I Feel It Coming>,
<Track: Contact>,
<Track: Voyager>,
<Track: One More Time (Short Radio Edit)>,
<Track: Starboy>,
<Track: Face to Face>,
<Track: Motherboard>]

The above returned a lot of tracks. If you wanted to search for artists instead, you may do so by specifying the relation argument:

>>> client.search('Daft Punk', relation='artist')
[<Artist: Daft Punk>,
 <Artist: Daft Punk - Stardust>,
 <Artist: Tribute to Daft Punk>,
 <Artist: Daft Punk feat. Pharrell Williams and Nile Rodgers>,
 <Artist: Made famous by Daft Punk>,
 <Artist: Daft Punk's Karaoke Band>]

The relation parameter accepts any resource name as value. The name of a resource is a string with the class name in lowercase. This is explained in a following section.

Main concepts

As we just seen above, the entry point is the Client class, which gives access to a number of methods. The methods are attempting to map to the REST API endpoints from Deezer.

You may have noticed from the above examples, but depending on the endpoint that is being called, the methods will return various type of resources. All the resources are listed in the resources reference page.

More examples

Getting a field about a resource

When you ge a resource, you have access to all the fields that are in the REST API response. For example, all the fields presented in the documentation for the track object are accessible as attribute on the Track resource:

>>> instant_crush
<Track: Instant Crush>
>>> instant_crush.duration
337
>>> instant_crush.readable
True
>>> instant_crush.disk_number
1

Getting the raw data

At some point, you might want to get the resources exported as Python dictionaries to store them somewhere else or transform them further.

Each resource has a asdict() method to export its content as dictionary:

>>> instant_crush.asdict()
{'id': 67238732,
 'readable': True,
 'title': 'Instant Crush',
 'title_short': 'Instant Crush',
 'title_version': '',
 'isrc': 'USQX91300105',
 'link': 'https://www.deezer.com/track/67238732',
 'duration': 337,
 'track_position': 5,
 ...}

Authentication

The deezer-python library doesn’t handle the authentication process, but it accepting an API token, which one can obtain using other libraries.

Obtaining a authentication token is better done client side, for example with Python Social Auth, which supports Deezer authentication.

Once the OAuth2 flow is complete, Deezer should give you a token which can be passed to the Client class:

client = deezer.Client(access_token='your-super-secret-token')

From there, you should be able to perform authenticated requests.