First steps

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

>>> client = deezer.Client()

While this usage is simple and convenient for using in the Python console, it’s best to use it as a context manager:

with deezer.Client() as client:

This is [the recommended way to use it by httpx](, which is the library we use under the hood.

From there, you can search for some terms:

>>>'Daft Punk')
<PaginatedList [
 <Track: One More Time>,
 <Track: I Feel It Coming>,
 <Track: Starboy>,
 <Track: Around the World>,
 <Track: Veridis Quo>,

The above returned a lot of tracks, wrapped in a PaginatedList, which is a list-like object (see the dedicated page about pagination for more details).

If you wanted to search for artists instead, you may use the Client.search_artists() method:

>>> client.search_artists('Daft Punk')
<PaginatedList [
 <Artist: Daft Punk>,
 <Artist: Daft Punk - Stardust>,
 <Artist: Tribute to Daft Punk>,
 <Artist: Daft Punk Experience>,
 <Artist: Daft Punk's Karaoke Band>,

Main concepts

As we have 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
>>> instant_crush.readable
>>> instant_crush.disk_number

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 as_dict() method to export its content as dictionary:

>>> instant_crush.as_dict()
{'id': 67238732,
 'readable': True,
 'title': 'Instant Crush',
 'title_short': 'Instant Crush',
 'title_version': '',
 'isrc': 'USQX91300105',
 'link': '',
 'duration': 337,
 'track_position': 5,


Deezer Python itself doesn’t handle the authentication & authorization, but it accepts an API token. Authentication tokens are issued for a specific user using the OAuth 2.0 protocol. The protocol states that the user needs to grant to your application the permissions you need, and this happens in the browser, on the Deezer website, which then redirect users to your application.

To integrate the OAuth flow in your application, we recommend looking at other libraries like 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.