UsersAPI¶

class minim.api.deezer.UsersAPI(client: APIClient, /)[source]¶

Bases: DeezerResourceAPI

Users API endpoints for the Deezer API.

Important

This class is managed by DeezerAPIClient and should not be instantiated directly.

Parameters:

clientminim.api._shared.APIClient: API client instance used to make HTTP requests.

Methods

`add_playlist_tracks`	Playlist > Tracks: Add tracks to a playlist.
`create_playlist`	User > Playlists: Create a playlist.
`delete_playlist`	Playlist: Delete a playlist.
`delete_track`	Track: Delete a user-uploaded track.
`follow_artists`	User > Artists: Favorite one or more artists.
`follow_playlists`	User > Playlists: Favorite one or more playlists.
`follow_podcast`	User > Podcasts: Favorite a podcast.
`follow_user`	User > Followings: Follow a user.
`get_user`	User: Get Deezer profile information for a user.
`get_user_album_recommendations`	User > Recommendations > Albums: Get Discogs catalog information for albums recommended for a user.
`get_user_artist_recommendations`	User > Recommendations > Artists: Get Discogs catalog information for artists recommended for a user.
`get_user_entitlements`	Options: Get the entitlements for a user on Deezer.
`get_user_followed_artists`	User > Artists: Get Deezer catalog information for a user's favorite artists.
`get_user_followed_podcasts`	User > Podcasts: Get Deezer catalog information for a user's favorite podcasts.
`get_user_followed_radios`	User > Radios: Get Deezer catalog information for a user's favorite radios.
`get_user_followers`	User > Followers: Get Deezer profile information for users following a specified user.
`get_user_followings`	User > Followings: Get Deezer profile information for users followed by a specified user.
`get_user_mix_tracks`	User > Flow: Get Deezer catalog information for the tracks in a user's Flow mix.
`get_user_permissions`	User > Permissions: Get the permissions granted to the Deezer API client by a user.
`get_user_playlist_recommendations`	User > Recommendations > Playlists: Get Discogs catalog information for playlists recommended for a user.
`get_user_playlists`	User > Playlists: Get Deezer catalog information for a user's playlists.
`get_user_radio_recommendations`	User > Recommendations > Radios: Get Discogs catalog information for radios recommended for a user.
`get_user_recently_played`	User > History: Get Deezer catalog information for the tracks recently played by a user on Deezer.
`get_user_release_recommendations`	User > Recommendations > Releases: Get Discogs catalog information for new releases recommended for a user.
`get_user_saved_albums`	User > Albums: Get Deezer catalog information for a user's favorite albums.
`get_user_saved_tracks`	User > Tracks: Get Deezer catalog information for a user's favorite tracks.
`get_user_top_albums`	User > Charts > Albums: Get Deezer catalog information for a user's top albums on Deezer.
`get_user_top_artists`	User > Charts > Artists: Get Deezer catalog information for a user's top artists on Deezer.
`get_user_top_playlists`	User > Charts > Playlists: Get Deezer catalog information for a user's top playlists.
`get_user_top_tracks`	User > Charts > Tracks: Get Deezer catalog information for a user's top tracks on Deezer.
`get_user_track_recommendations`	User > Recommendations > Tracks: Get Discogs catalog information for tracks recommended for a user.
`get_user_tracks`	User > Personal Songs: Get Deezer catalog information for a user's uploaded tracks.
`remove_episode_resume_point`	Episode > Bookmark: Remove a resume point for a podcast episode.
`remove_saved_album`	User > Albums: Unfavorite an album.
`remove_saved_radio`	User > Radios: Unfavorite a radio.
`remove_saved_track`	User > Tracks: Unfavorite a track.
`reorder_playlist_tracks`	Playlist > Tracks: Reorder tracks in a playlist.
`save_albums`	User > Albums: Favorite one or more albums.
`save_radio`	User > Radios: Favorite a radio.
`save_tracks`	User > Tracks: Favorite one or more tracks.
`send_user_notification`	User > Notification: Add a notification to a user's feed on Deezer.
`set_episode_resume_point`	Episode > Bookmark: Set a resume point for a podcast episode.
`unfollow_artist`	User > Artists: Unfavorite an artist.
`unfollow_playlist`	User > Playlists: Unfavorite a playlist.
`unfollow_podcast`	User > Podcasts: Unfavorite a podcast.
`unfollow_user`	User > Followings: Unfollow a user.
`update_playlist_details`	Playlist: Update the details of a playlist.
`update_track_metadata`	Track: Update the metadata for a user-uploaded track.

add_playlist_tracks(playlist_id: int | str, /, track_ids: int | str | Collection[int | str]) → bool[source]¶

Playlist > Tracks: Add tracks to a playlist.

Permission

Required

manage_library permission: Manage a user’s library. Learn more.

Parameters:

playlist_idint or str; positional-only

Deezer ID of the playlist.

Examples: 13651021241, "1495242491".

track_idsint, str, or Collection[int | str]

Deezer IDs of the tracks.

Examples: 101602968, "3541756661", "101602968,3541756661", [101602968, "3541756661"].

Returns:

successbool: Whether the tracks were added successfully.

create_playlist(name: str, /, *, user_id: int | str = 'me') → dict[str, int][source]¶

User > Playlists: Create a playlist.

Permission

Required

manage_library permission: Manage a user’s library. Learn more.

Parameters:

namestr

Playlist name.

Example: "My New Playlist Title".

user_idint or str; keyword-only; default: "me"

Deezer ID of the user. If authenticated, "me" can be used in lieu of a Deezer ID for the current user.

Example: 5395005364, "5395005364", "me".

Returns:

playlist_iddict[str, int]

Deezer ID of the newly created playlist.

Sample response: {"id": <int>}.

delete_playlist(playlist_id: int | str, /) → bool[source]¶

Playlist: Delete a playlist.

Permissions

Required

manage_library permission: Manage a user’s library. Learn more.
delete_library permission: Delete items from a user’s library. Learn more.

Parameters:

playlist_idint or str; positional-only

Deezer ID of the playlist.

Examples: 13651021241, "1495242491".

Returns:

successbool: Whether the playlist was deleted successfully.

delete_track(track_id: int | str, /) → bool[source]¶

Track: Delete a user-uploaded track.

Permission

Required

delete_library permission: Delete items from a user’s library. Learn more.

Parameters:

track_idint or str; positional-only

Deezer ID of the track.

Examples: -3140371023, "-3140371043".

Returns:

successbool: Whether the track was deleted successfully.

follow_artists(artist_ids: int | str | Collection[int | str], /, *, user_id: int | str = 'me') → bool[source]¶

User > Artists: Favorite one or more artists.

Permission

Required

manage_library permission: Manage a user’s library. Learn more.

Parameters:

artist_idsint, str, or Collection[int | str]; positional-only

Deezer IDs of the artists.

Examples: 3265001, "330311461", "3265001,330311461", [3265001, "330311461"].

user_idint or str; keyword-only; default: "me"

Deezer ID of the user. If authenticated, "me" can be used in lieu of a Deezer ID for the current user.

Example: 5395005364, "5395005364", "me".

Returns:

successbool: Whether the artists were favorited successfully.

follow_playlists(playlist_ids: int | str | Collection[int | str], /, *, user_id: int | str = 'me') → bool[source]¶

User > Playlists: Favorite one or more playlists.

Permission

Required

manage_library permission: Manage a user’s library. Learn more.

Parameters:

playlist_idsint, str, or Collection[int | str]; positional-only

Deezer IDs of the playlists.

Examples: 13651021241, "1495242491", "13651021241,1495242491", [13651021241, "1495242491"].

user_idint or str; keyword-only; default: "me"

Deezer ID of the user. If authenticated, "me" can be used in lieu of a Deezer ID for the current user.

Example: 5395005364, "5395005364", "me".

Returns:

successbool: Whether the playlists were favorited successfully.

follow_podcast(podcast_id: int | str, /, *, user_id: int | str = 'me') → bool[source]¶

User > Podcasts: Favorite a podcast.

Permission

Required

manage_library permission: Manage a user’s library. Learn more.

Parameters:

podcast_idint or str; positional-only

Deezer ID of the podcast.

Examples: 436862, "2740882".

user_idint or str; keyword-only; default: "me"

Deezer ID of the user. If authenticated, "me" can be used in lieu of a Deezer ID for the current user.

Example: 5395005364, "5395005364", "me".

Returns:

successbool: Whether the podcast was favorited successfully.

follow_user(follow_user_id: int | str, /, *, user_id: int | str = 'me') → bool[source]¶

User > Followings: Follow a user.

Permission

Required

manage_community permission: Manage a user’s friends. Learn more.

Parameters:

follow_user_idint or str; positional-only

Deezer ID of the user to follow.

Example: 5395005364, "5395005364".

user_idint or str; keyword-only; default: "me"

Deezer ID of the user. If authenticated, "me" can be used in lieu of a Deezer ID for the current user.

Example: 5395005364, "5395005364", "me".

Returns:

successbool: Whether the user was followed successfully.

get_user(user_id: int | str = 'me', /) → dict[str, Any][source]¶

User: Get Deezer profile information for a user.

Permission and user authentication

Required

User authentication: Access the user’s basic information.

Optional

email permission: Access the user’s email. Learn more.

Parameters:

user_idint or str; positional-only; default: "me"

Deezer ID of the user. If authenticated, "me" can be used in lieu of a Deezer ID for the current user.

Example: 5395005364, "5395005364", "me".

Returns:

profiledict[str, Any]

Deezer metadata for the user’s profile.

Sample response

{
  "birthday": <str>,
  "country": <str>,
  "email": <str>,
  "explicit_content_level": <str>,
  "explicit_content_levels_available": <list[str]>,
  "firstname": <str>,
  "gender": <str>,
  "id": <int>,
  "inscription_date": <str>,
  "is_kid": <bool>,
  "lang": <str>,
  "lastname": <str>,
  "link": <str>,
  "name": <str>,
  "picture": <str>,
  "picture_big": <str>,
  "picture_medium": <str>,
  "picture_small": <str>,
  "picture_xl": <str>,
  "status": <int>,
  "tracklist": <str>,
  "type": "user"
}

get_user_album_recommendations(user_id: int | str = 'me', /, *, limit: int | None = None, offset: int | None = None) → dict[str, Any][source]¶

User > Recommendations > Albums: Get Discogs catalog information for albums recommended for a user.

User authentication

Required

User authentication: Access the user’s favorite items, playlists, and followed people.

Parameters:

user_idint or str; positional-only; default: "me"

Deezer ID of the user. If authenticated, "me" can be used in lieu of a Deezer ID for the current user.

Example: 5395005364, "5395005364", "me".

limitint; keyword-only; optional

Maximum number of albums to return.

Minimum value: 1.

offsetint; keyword-only; optional

Index of the first album to return. Use with limit to get the next batch of albums.

Minimum value: 0.

API default: 0.

Returns:

albumsdict[str, Any]

Page of Deezer metadata for the recommended albums.

Sample response

{
  "data": [
    {
      "artist": {
        "id": <int>,
        "name": <str>,
        "picture": <str>,
        "picture_big": <str>,
        "picture_medium": <str>,
        "picture_small": <str>,
        "picture_xl": <str>,
        "tracklist": <str>,
        "type": "artist"
      },
      "available": <bool>,
      "cover": <str>,
      "cover_big": <str>,
      "cover_medium": <str>,
      "cover_small": <str>,
      "cover_xl": <str>,
      "explicit_lyrics": <bool>,
      "id": <int>,
      "link": <str>,
      "md5_image": <str>,
      "nb_tracks": <int>,
      "record_type": <str>,
      "release_date": <str>,
      "timestamp": <int>,
      "title": <str>,
      "tracklist": <str>,
      "type": "album"
    }
  ],
  "next": <str>,
  "prev": <str>,
  "total": <int>
}

get_user_artist_recommendations(user_id: int | str = 'me', /, *, limit: int | None = None, offset: int | None = None) → dict[str, Any][source]¶

User > Recommendations > Artists: Get Discogs catalog information for artists recommended for a user.

User authentication

Required

User authentication: Access the user’s favorite items, playlists, and followed people.

Parameters:

user_idint or str; positional-only; default: "me"

Deezer ID of the user. If authenticated, "me" can be used in lieu of a Deezer ID for the current user.

Example: 5395005364, "5395005364", "me".

limitint; keyword-only; optional

Maximum number of artists to return.

Minimum value: 1.

offsetint; keyword-only; optional

Index of the first artist to return. Use with limit to get the next batch of artists.

Minimum value: 0.

API default: 0.

Returns:

artistsdict[str, Any]

Page of Deezer metadata for the recommended artists.

Sample response

{
  "data": [
    {
      "id": <int>,
      "link": <str>,
      "name": <str>,
      "nb_album": <int>,
      "nb_fan": <int>,
      "picture": <str>,
      "picture_big": <str>,
      "picture_medium": <str>,
      "picture_small": <str>,
      "picture_xl": <str>,
      "radio": <bool>,
      "timestamp": <int>,
      "tracklist": <str>,
      "type": "artist"
    }
  ],
  "next": <str>,
  "prev": <str>,
  "total": <int>
}

get_user_entitlements(user_id: int | str = 'me', /) → dict[str, Any][source]¶

Options: Get the entitlements for a user on Deezer.

Permission and user authentication

Required

User authentication: Access the user’s basic information.

Parameters:

user_idint or str; positional-only; default: "me"

Deezer ID of the user. If authenticated, "me" can be used in lieu of a Deezer ID for the current user.

Example: 5395005364, "5395005364", "me".

Returns:

entitlements: dict[str, Any]

User’s entitlement.

Sample response

{
  "ads_audio": <bool>,
  "ads_display": <bool>,
  "can_subscribe": <bool>,
  "hq": <bool>,
  "lossless": <bool>,
  "offline": <bool>,
  "preview": <bool>,
  "radio": <bool>,
  "radio_skips": <int>,
  "streaming": <bool>,
  "streaming_duration": <int>,
  "too_many_devices": <bool>,
  "type": "options"
}

get_user_followed_artists(user_id: int | str = 'me', /, *, limit: int | None = None, offset: int | None = None) → dict[str, Any][source]¶

User > Artists: Get Deezer catalog information for a user’s favorite artists.

User authentication

Required

User authentication: Access the user’s favorite items, playlists, and followed people.

Parameters:

user_idint or str; positional-only; default: "me"

Deezer ID of the user. If authenticated, "me" can be used in lieu of a Deezer ID for the current user.

Example: 5395005364, "5395005364", "me".

limitint; keyword-only; optional

Maximum number of artists to return.

Minimum value: 1.

offsetint; keyword-only; optional

Index of the first artist to return. Use with limit to get the next batch of artists.

Minimum value: 0.

API default: 0.

Returns:

artistsdict[str, Any]

Page of Deezer metadata for the user’s favorite artists.

Sample response

{
  "checksum": <str>,
  "data": [
    {
      "id": <int>,
      "link": <str>,
      "name": <str>,
      "nb_album": <int>,
      "nb_fan": <int>,
      "picture": <str>,
      "picture_big": <str>,
      "picture_medium": <str>,
      "picture_small": <str>,
      "picture_xl": <str>,
      "radio": <bool>,
      "time_add": <int>,
      "tracklist": <str>,
      "type": "artist"
    }
  ],
  "next": <str>,
  "prev": <str>,
  "total": <int>
}

get_user_followed_podcasts(user_id: int | str = 'me', /, *, limit: int | None = None, offset: int | None = None) → dict[str, Any][source]¶

User > Podcasts: Get Deezer catalog information for a user’s favorite podcasts.

User authentication

Required

User authentication: Access the user’s favorite items, playlists, and followed people.

Parameters:

user_idint or str; positional-only; default: "me"

Deezer ID of the user. If authenticated, "me" can be used in lieu of a Deezer ID for the current user.

Example: 5395005364, "5395005364", "me".

limitint; keyword-only; optional

Maximum number of podcasts to return.

Minimum value: 1.

offsetint; keyword-only; optional

Index of the first podcast to return. Use with limit to get the next batch of podcasts.

Minimum value: 0.

API default: 0.

Returns:

podcastsdict[str, Any]

Page of Deezer metadata for the user’s favorite podcasts.

Sample response

{
  "checksum": <str>,
  "data": [
    {
      "available": <bool>,
      "description": <str>,
      "fans": <int>,
      "id": <int>,
      "link": <str>,
      "picture": <str>,
      "picture_big": <str>,
      "picture_medium": <str>,
      "picture_small": <str>,
      "picture_xl": <str>,
      "share": <str>,
      "time_add": <int>,
      "title": <str>,
      "type": "podcast"
    }
  ],
  "next": <str>,
  "prev": <str>,
  "total": <int>
}

get_user_followed_radios(user_id: int | str = 'me', /, *, limit: int | None = None, offset: int | None = None) → dict[str, Any][source]¶

User > Radios: Get Deezer catalog information for a user’s favorite radios.

User authentication

Required

User authentication: Access the user’s favorite items, playlists, and followed people.

Parameters:

user_idint or str; positional-only; default: "me"

Deezer ID of the user. If authenticated, "me" can be used in lieu of a Deezer ID for the current user.

Example: 5395005364, "5395005364", "me".

limitint; keyword-only; optional

Maximum number of radios to return.

Minimum value: 1.

offsetint; keyword-only; optional

Index of the first radio to return. Use with limit to get the next batch of radios.

Minimum value: 0.

API default: 0.

Returns:

radiosdict[str, Any]

Page of Deezer metadata for the user’s favorite radios.

Sample response

{
  "checksum": <str>,
  "data": [],
  "next": <str>,
  "prev": <str>,
  "total": <int>
}

get_user_followers(user_id: int | str = 'me', /, *, limit: int | None = None, offset: int | None = None) → dict[str, Any][source]¶

User > Followers: Get Deezer profile information for users following a specified user.

User authentication

Required

User authentication: Access the user’s favorite items, playlists, and followed people.

Parameters:

user_idint or str; positional-only; default: "me"

Deezer ID of the user. If authenticated, "me" can be used in lieu of a Deezer ID for the current user.

Example: 5395005364, "5395005364", "me".

limitint; keyword-only; optional

Maximum number of users to return.

Minimum value: 1.

offsetint; keyword-only; optional

Index of the first user to return. Use with limit to get the next batch of users.

Minimum value: 0.

API default: 0.

Returns:

usersdict[str, Any]

Page of Deezer profile information for the user’s followers.

Sample response

{
  "data": [
    {
      "id": <int>,
      "name": <str>,
      "picture": <str>,
      "picture_big": <str>,
      "picture_medium": <str>,
      "picture_small": <str>,
      "picture_xl": <str>,
      "tracklist": <str>,
      "type": "user"
    }
  ],
  "next": <str>,
  "prev": <str>,
  "total": <int>
}

get_user_followings(user_id: int | str = 'me', /, *, limit: int | None = None, offset: int | None = None) → dict[str, Any][source]¶

User > Followings: Get Deezer profile information for users followed by a specified user.

User authentication

Required

User authentication: Access the user’s favorite items, playlists, and followed people.

Parameters:

user_idint or str; positional-only; default: "me"

Deezer ID of the user. If authenticated, "me" can be used in lieu of a Deezer ID for the current user.

Example: 5395005364, "5395005364", "me".

limitint; keyword-only; optional

Maximum number of users to return.

Minimum value: 1.

offsetint; keyword-only; optional

Index of the first user to return. Use with limit to get the next batch of users.

Minimum value: 0.

API default: 0.

Returns:

usersdict[str, Any]

Page of Deezer profile information for the followed users.

Sample response

{
  "data": [
    {
      "id": <int>,
      "name": <str>,
      "picture": <str>,
      "picture_big": <str>,
      "picture_medium": <str>,
      "picture_small": <str>,
      "picture_xl": <str>,
      "tracklist": <str>,
      "type": "user"
    }
  ],
  "next": <str>,
  "prev": <str>,
  "total": <int>
}

get_user_mix_tracks(user_id: int | str = 'me', /) → dict[str, Any][source]¶

User > Flow: Get Deezer catalog information for the tracks in a user’s Flow mix.

User authentication

Required

User authentication: Access the user’s favorite items, playlists, and followed people.

Parameters:

user_idint or str; positional-only; default: "me"

Deezer ID of the user. If authenticated, "me" can be used in lieu of a Deezer ID for the current user.

Example: 5395005364, "5395005364", "me".

Returns:

tracksdict[str, Any]

Deezer metadata for tracks in the user’s Flow mix.

Sample response

{
  "data": [
    {
      "album": {
        "cover": <str>,
        "cover_big": <str>,
        "cover_medium": <str>,
        "cover_small": <str>,
        "cover_xl": <str>,
        "id": <int>,
        "md5_image": <str>,
        "title": <str>,
        "tracklist": <str>,
        "type": "album"
      },
      "artist": {
        "id": <int>,
        "name": <str>,
        "picture": <str>,
        "picture_big": <str>,
        "picture_medium": <str>,
        "picture_small": <str>,
        "picture_xl": <str>,
        "tracklist": <str>,
        "type": "artist"
      },
      "duration": <int>,
      "explicit_content_cover": <int>,
      "explicit_content_lyrics": <int>,
      "explicit_lyrics": <bool>,
      "id": <int>,
      "md5_image": <str>,
      "preview": <str>,
      "rank": <int>,
      "readable": <bool>,
      "title": <str>,
      "title_short": <str>,
      "title_version": <str>,
      "type": "track"
    }
  ]
}

get_user_permissions(user_id: int | str = 'me', /) → dict[str, dict[str, bool]][source]¶

User > Permissions: Get the permissions granted to the Deezer API client by a user.

Permission and user authentication

Required

User authentication: Access the user’s basic information.

Parameters:

user_idint or str; positional-only; default: "me"

Deezer ID of the user. If authenticated, "me" can be used in lieu of a Deezer ID for the current user.

Example: 5395005364, "5395005364", "me".

Returns:

permissions: dict[str, dict[str, bool]]

Permissions granted to the client by the user.

Sample response

{
  "permissions": {
    "basic_access": true,
    "delete_library": true,
    "email": true,
    "listening_history": true,
    "manage_community": true,
    "manage_library": true,
    "offline_access": true
  }
}

get_user_playlist_recommendations(user_id: int | str = 'me', /, *, limit: int | None = None, offset: int | None = None) → dict[str, Any][source]¶

User > Recommendations > Playlists: Get Discogs catalog information for playlists recommended for a user.

User authentication

Required

User authentication: Access the user’s favorite items, playlists, and followed people.

Parameters:

user_idint or str; positional-only; default: "me"

Deezer ID of the user. If authenticated, "me" can be used in lieu of a Deezer ID for the current user.

Example: 5395005364, "5395005364", "me".

limitint; keyword-only; optional

Maximum number of playlists to return.

Minimum value: 1.

offsetint; keyword-only; optional

Index of the first playlist to return. Use with limit to get the next batch of playlists.

Minimum value: 0.

API default: 0.

Returns:

playlistsdict[str, Any]

Page of Deezer metadata for the recommended playlists.

Sample response

{
  "data": [
    {
      "add_date": <str>,
      "checksum": <str>,
      "collaborative": <bool>,
      "creation_date": <str>,
      "creator": {
        "id": <int>,
        "name": <str>,
        "tracklist": <str>,
        "type": "user"
      },
      "duration": <int>,
      "fans": <int>,
      "id": <int>,
      "is_loved_track": <bool>,
      "link": <str>,
      "md5_image": <str>,
      "mod_date": <str>,
      "nb_tracks": <int>,
      "picture": <str>,
      "picture_big": <str>,
      "picture_medium": <str>,
      "picture_small": <str>,
      "picture_type": <str>,
      "picture_xl": <str>,
      "public": <bool>,
      "timestamp": <int>,
      "title": <str>,
      "tracklist": <str>,
      "type": "playlist"
    }
  ],
  "next": <str>,
  "prev": <str>,
  "total": <int>
}

get_user_playlists(user_id: int | str = 'me', /, *, limit: int | None = None, offset: int | None = None) → dict[str, Any][source]¶

User > Playlists: Get Deezer catalog information for a user’s playlists.

User authentication

Required

User authentication: Access the user’s favorite items, playlists, and followed people.

Parameters:

user_idint or str; positional-only; default: "me"

Deezer ID of the user. If authenticated, "me" can be used in lieu of a Deezer ID for the current user.

Example: 5395005364, "5395005364", "me".

limitint; keyword-only; optional

Maximum number of playlists to return.

Minimum value: 1.

offsetint; keyword-only; optional

Index of the first playlist to return. Use with limit to get the next batch of playlists.

Minimum value: 0.

API default: 0.

Returns:

playlistsdict[str, Any]

Page of Deezer metadata for the user’s playlists.

Sample response

{
  "data": [
    {
      "add_date": <str>,
      "checksum": <str>,
      "collaborative": <bool>,
      "creation_date": <str>,
      "creator": {
        "id": <int>,
        "name": <str>,
        "tracklist": <str>,
        "type": "user"
      },
      "duration": <int>,
      "fans": <int>,
      "id": <int>,
      "is_loved_track": <bool>,
      "link": <str>,
      "md5_image": <str>,
      "mod_date": <str>,
      "nb_tracks": <int>,
      "picture": <str>,
      "picture_big": <str>,
      "picture_medium": <str>,
      "picture_small": <str>,
      "picture_type": <str>,
      "picture_xl": <str>,
      "public": <bool>,
      "time_add": <int>,
      "time_mod": <int>,
      "title": <str>,
      "tracklist": <str>,
      "type": "playlist"
    }
  ],
  "next": <str>,
  "prev": <str>,
  "total": <int>
}

get_user_radio_recommendations(user_id: int | str = 'me', /, *, limit: int | None = None, offset: int | None = None) → dict[str, Any][source]¶

User > Recommendations > Radios: Get Discogs catalog information for radios recommended for a user.

User authentication

Required

User authentication: Access the user’s favorite items, playlists, and followed people.

Parameters:

user_idint or str; positional-only; default: "me"

Deezer ID of the user. If authenticated, "me" can be used in lieu of a Deezer ID for the current user.

Example: 5395005364, "5395005364", "me".

limitint; keyword-only; optional

Maximum number of radios to return.

Minimum value: 1.

offsetint; keyword-only; optional

Index of the first radio to return. Use with limit to get the next batch of radios.

Minimum value: 0.

API default: 0.

Returns:

radiosdict[str, Any]

Page of Deezer metadata for the recommended radios.

Sample response

{
  "data": [
    {
      "id": <int>,
      "md5_image": <str>,
      "picture": <str>,
      "picture_big": <str>,
      "picture_medium": <str>,
      "picture_small": <str>,
      "picture_xl": <str>,
      "timestamp": <int>,
      "title": <str>,
      "tracklist": <str>,
      "type": "radio"
    }
  ],
  "next": <str>,
  "prev": <str>,
  "total": <int>
}

get_user_recently_played(user_id: int | str = 'me', /, *, limit: int | None = None, offset: int | None = None) → dict[str, Any][source]¶

User > History: Get Deezer catalog information for the tracks recently played by a user on Deezer.

Permission

Required

listening_history permission: Access the user’s listening history. Learn more.

Parameters:

user_idint or str; positional-only; default: "me"

Deezer ID of the user. If authenticated, "me" can be used in lieu of a Deezer ID for the current user.

Example: 5395005364, "5395005364", "me".

limitint; keyword-only; optional

Maximum number of tracks to return.

Minimum value: 1.

offsetint; keyword-only; optional

Index of the first track to return. Use with limit to get the next batch of tracks.

Minimum value: 0.

API default: 0.

Returns:

tracksdict[str, Any]

Page of Deezer metadata for the user’s recently played tracks.

Sample response

{
  "data": [
    {
      "album": {
        "cover": <str>,
        "cover_big": <str>,
        "cover_medium": <str>,
        "cover_small": <str>,
        "cover_xl": <str>,
        "id": <int>,
        "md5_image": <str>,
        "title": <str>,
        "tracklist": <str>,
        "type": "album"
      },
      "artist": {
        "id": <int>,
        "name": <str>,
        "picture": <str>,
        "picture_big": <str>,
        "picture_medium": <str>,
        "picture_small": <str>,
        "picture_xl": <str>,
        "tracklist": <str>,
        "type": "artist"
      },
      "duration": <int>,
      "explicit_content_cover": <int>,
      "explicit_content_lyrics": <int>,
      "explicit_lyrics": <bool>,
      "id": <int>,
      "md5_image": <str>,
      "preview": <str>,
      "rank": <int>,
      "readable": <bool>,
      "title": <str>,
      "title_short": <str>,
      "title_version": <str>,
      "type": "track"
    }
  ],
  "next": <str>,
  "prev": <str>,
  "total": <int>
}

get_user_release_recommendations(user_id: int | str = 'me', /, *, limit: int | None = None, offset: int | None = None) → dict[str, Any][source]¶

User > Recommendations > Releases: Get Discogs catalog information for new releases recommended for a user.

User authentication

Required

User authentication: Access the user’s favorite items, playlists, and followed people.

Parameters:

user_idint or str; positional-only; default: "me"

Deezer ID of the user. If authenticated, "me" can be used in lieu of a Deezer ID for the current user.

Example: 5395005364, "5395005364", "me".

limitint; keyword-only; optional

Maximum number of releases to return.

Minimum value: 1.

offsetint; keyword-only; optional

Index of the first release to return. Use with limit to get the next batch of releases.

Minimum value: 0.

API default: 0.

Returns:

releasesdict[str, Any]

Page of Deezer metadata for the recommended new releases.

Sample response

{
  "data": [
    {
      "artist": {
        "id": <int>,
        "name": <str>,
        "picture": <str>,
        "picture_big": <str>,
        "picture_medium": <str>,
        "picture_small": <str>,
        "picture_xl": <str>,
        "tracklist": <str>,
        "type": "artist"
      },
      "available": <bool>,
      "cover": <str>,
      "cover_big": <str>,
      "cover_medium": <str>,
      "cover_small": <str>,
      "cover_xl": <str>,
      "explicit_lyrics": <bool>,
      "id": <int>,
      "link": <str>,
      "md5_image": <str>,
      "nb_tracks": <int>,
      "record_type": <str>,
      "release_date": <str>,
      "timestamp": <int>,
      "title": <str>,
      "tracklist": <str>,
      "type": "album"
    }
  ],
  "next": <str>,
  "prev": <str>,
  "total": <int>,
}

get_user_saved_albums(user_id: int | str = 'me', /, *, limit: int | None = None, offset: int | None = None) → dict[str, Any][source]¶

User > Albums: Get Deezer catalog information for a user’s favorite albums.

User authentication

Required

User authentication: Access the user’s favorite items, playlists, and followed people.

Parameters:

user_idint or str; positional-only; default: "me"

Deezer ID of the user. If authenticated, "me" can be used in lieu of a Deezer ID for the current user.

Example: 5395005364, "5395005364", "me".

limitint; keyword-only; optional

Maximum number of albums to return.

Minimum value: 1.

offsetint; keyword-only; optional

Index of the first album to return. Use with limit to get the next batch of albums.

Minimum value: 0.

API default: 0.

Returns:

albumsdict[str, Any]

Page of Deezer metadata for the user’s favorite albums.

Sample response

{
  "checksum": <str>,
  "data": [
    {
      "artist": {
        "id": <int>,
        "name": <str>,
        "picture": <str>,
        "picture_big": <str>,
        "picture_medium": <str>,
        "picture_small": <str>,
        "picture_xl": <str>,
        "tracklist": <str>,
        "type": "artist"
      },
      "available": <bool>,
      "cover": <str>,
      "cover_big": <str>,
      "cover_medium": <str>,
      "cover_small": <str>,
      "cover_xl": <str>,
      "explicit_lyrics": <bool>,
      "id": <int>,
      "link": <str>,
      "md5_image": <str>,
      "nb_tracks": <int>,
      "record_type": <str>,
      "release_date": <str>,
      "time_add": <int>,
      "title": <str>,
      "tracklist": <str>,
      "type": "album"
    }
  ],
  "next": <str>,
  "prev": <str>,
  "total": <int>
}

get_user_saved_tracks(user_id: int | str = 'me', /, *, limit: int | None = None, offset: int | None = None) → dict[str, Any][source]¶

User > Tracks: Get Deezer catalog information for a user’s favorite tracks.

User authentication

Required

User authentication: Access the user’s favorite items, playlists, and followed people.

Parameters:

user_idint or str; positional-only; default: "me"

Deezer ID of the user. If authenticated, "me" can be used in lieu of a Deezer ID for the current user.

Example: 5395005364, "5395005364", "me".

limitint; keyword-only; optional

Maximum number of tracks to return.

Minimum value: 1.

offsetint; keyword-only; optional

Index of the first track to return. Use with limit to get the next batch of tracks.

Minimum value: 0.

API default: 0.

Returns:

tracksdict[str, Any]

Page of Deezer metadata for the user’s favorite tracks.

Sample response

{
  "checksum": <str>,
  "data": [
    {
      "album": {
        "cover": <str>,
        "cover_big": <str>,
        "cover_medium": <str>,
        "cover_small": <str>,
        "cover_xl": <str>,
        "id": <int>,
        "md5_image": <str>,
        "title": <str>,
        "tracklist": <str>,
        "type": "album"
      },
      "artist": {
        "id": <int>,
        "name": <str>,
        "picture": <str>,
        "picture_big": <str>,
        "picture_medium": <str>,
        "picture_small": <str>,
        "picture_xl": <str>,
        "tracklist": <str>,
        "type": "artist"
      },
      "duration": <int>,
      "explicit_content_cover": <int>,
      "explicit_content_lyrics": <int>,
      "explicit_lyrics": <bool>,
      "id": <int>,
      "md5_image": <str>,
      "preview": <str>,
      "rank": <int>,
      "readable": <bool>,
      "title": <str>,
      "title_short": <str>,
      "title_version": <str>,
      "type": "track"
    }
  ],
  "next": <str>,
  "prev": <str>,
  "total": <int>
}

get_user_top_albums(user_id: int | str = 'me', /, *, limit: int | None = None, offset: int | None = None) → dict[str, Any][source]¶

User > Charts > Albums: Get Deezer catalog information for a user’s top albums on Deezer.

User authentication

Required

User authentication: Access the user’s favorite items, playlists, and followed people.

Parameters:

user_idint or str; positional-only; default: "me"

Deezer ID of the user. If authenticated, "me" can be used in lieu of a Deezer ID for the current user.

Example: 5395005364, "5395005364", "me".

limitint; keyword-only; optional

Maximum number of albums to return.

Minimum value: 1.

offsetint; keyword-only; optional

Index of the first album to return. Use with limit to get the next batch of albums.

Minimum value: 0.

API default: 0.

Returns:

albumsdict[str, Any]

Page of Deezer metadata for the user’s top albums.

Sample response

{
  "checksum": <str>,
  "data": [
    {
      "artist": {
        "id": <int>,
        "name": <str>,
        "picture": <str>,
        "picture_big": <str>,
        "picture_medium": <str>,
        "picture_small": <str>,
        "picture_xl": <str>,
        "tracklist": <str>,
        "type": "artist"
      },
      "available": <bool>,
      "cover": <str>,
      "cover_big": <str>,
      "cover_medium": <str>,
      "cover_small": <str>,
      "cover_xl": <str>,
      "explicit_lyrics": <bool>,
      "id": <int>,
      "link": <str>,
      "md5_image": <str>,
      "nb_tracks": <int>,
      "record_type": <str>,
      "release_date": <str>,
      "title": <str>,
      "tracklist": <str>,
      "type": "album"
    }
  ],
  "next": <str>,
  "prev": <str>,
  "total": <int>
}

get_user_top_artists(user_id: int | str = 'me', /, *, limit: int | None = None, offset: int | None = None) → dict[str, Any][source]¶

User > Charts > Artists: Get Deezer catalog information for a user’s top artists on Deezer.

User authentication

Required

User authentication: Access the user’s favorite items, playlists, and followed people.

Parameters:

user_idint or str; positional-only; default: "me"

Deezer ID of the user. If authenticated, "me" can be used in lieu of a Deezer ID for the current user.

Example: 5395005364, "5395005364", "me".

limitint; keyword-only; optional

Maximum number of artists to return.

Minimum value: 1.

offsetint; keyword-only; optional

Index of the first artist to return. Use with limit to get the next batch of artists.

Minimum value: 0.

API default: 0.

Returns:

artistsdict[str, Any]

Page of Deezer metadata for the user’s top artists.

Sample response

{
  "checksum": <str>,
  "data": [
    {
      "id": <int>,
      "link": <str>,
      "name": <str>,
      "nb_album": <int>,
      "nb_fan": <int>,
      "picture": <str>,
      "picture_big": <str>,
      "picture_medium": <str>,
      "picture_small": <str>,
      "picture_xl": <str>,
      "radio": <bool>,
      "tracklist": <str>,
      "type": "artist"
    }
  ],
  "next": <str>,
  "prev": <str>,
  "total": <int>
}

get_user_top_playlists(user_id: int | str = 'me', /, *, limit: int | None = None, offset: int | None = None) → dict[str, Any][source]¶

User > Charts > Playlists: Get Deezer catalog information for a user’s top playlists.

User authentication

Required

User authentication: Access the user’s favorite items, playlists, and followed people.

Parameters:

user_idint or str; positional-only; default: "me"

Deezer ID of the user. If authenticated, "me" can be used in lieu of a Deezer ID for the current user.

Example: 5395005364, "5395005364", "me".

limitint; keyword-only; optional

Maximum number of playlists to return.

Minimum value: 1.

offsetint; keyword-only; optional

Index of the first playlist to return. Use with limit to get the next batch of playlists.

Minimum value: 0.

API default: 0.

Returns:

playlistsdict[str, Any]

Page of Deezer metadata for the user’s top playlists.

Sample response

{
  "checksum": <str>,
  "data": [
    {
      "add_date": <str>,
      "checksum": <str>,
      "collaborative": <bool>,
      "creation_date": <str>,
      "creator": {
        "id": <int>,
        "name": <str>,
        "tracklist": <str>,
        "type": "user"
      },
      "duration": <int>,
      "fans": <int>,
      "id": <int>,
      "is_loved_track": <bool>,
      "link": <str>,
      "md5_image": <str>,
      "mod_date": <str>,
      "nb_tracks": <int>,
      "picture": <str>,
      "picture_big": <str>,
      "picture_medium": <str>,
      "picture_small": <str>,
      "picture_type": <str>,
      "picture_xl": <str>,
      "public": <bool>,
      "title": <str>,
      "tracklist": <str>,
      "type": "playlist"
    }
  ],
  "next": <str>,
  "prev": <str>,
  "total": <int>
}

get_user_top_tracks(user_id: int | str = 'me', /, *, limit: int | None = None, offset: int | None = None) → dict[str, Any][source]¶

User > Charts > Tracks: Get Deezer catalog information for a user’s top tracks on Deezer.

User authentication

Required

User authentication: Access the user’s favorite items, playlists, and followed people.

Parameters:

user_idint or str; positional-only; default: "me"

Deezer ID of the user. If authenticated, "me" can be used in lieu of a Deezer ID for the current user.

Example: 5395005364, "5395005364", "me".

limitint; keyword-only; optional

Maximum number of tracks to return.

Minimum value: 1.

offsetint; keyword-only; optional

Index of the first track to return. Use with limit to get the next batch of tracks.

Minimum value: 0.

API default: 0.

Returns:

tracksdict[str, Any]

Page of Deezer metadata for the user’s top tracks.

Sample response

{
  "checksum": <str>,
  "data": [
    {
      "album": {
        "cover": <str>,
        "cover_big": <str>,
        "cover_medium": <str>,
        "cover_small": <str>,
        "cover_xl": <str>,
        "id": <int>,
        "md5_image": <str>,
        "title": <str>,
        "tracklist": <str>,
        "type": "album"
      },
      "artist": {
        "id": <int>,
        "name": <str>,
        "picture": <str>,
        "picture_big": <str>,
        "picture_medium": <str>,
        "picture_small": <str>,
        "picture_xl": <str>,
        "tracklist": <str>,
        "type": "artist"
      },
      "duration": <int>,
      "explicit_content_cover": <int>,
      "explicit_content_lyrics": <int>,
      "explicit_lyrics": <bool>,
      "id": <int>,
      "md5_image": <str>,
      "preview": <str>,
      "rank": <int>,
      "readable": <bool>,
      "title": <str>,
      "title_short": <str>,
      "title_version": <str>,
      "type": "track"
    }
  ],
  "next": <str>,
  "prev": <str>,
  "total": <int>
}

get_user_track_recommendations(user_id: int | str = 'me', /) → dict[str, Any][source]¶

User > Recommendations > Tracks: Get Discogs catalog information for tracks recommended for a user.

User authentication

Required

User authentication: Access the user’s favorite items, playlists, and followed people.

Parameters:

user_idint or str; positional-only; default: "me"

Deezer ID of the user. If authenticated, "me" can be used in lieu of a Deezer ID for the current user.

Example: 5395005364, "5395005364", "me".

limitint; keyword-only; optional

Maximum number of tracks to return.

Minimum value: 1.

offsetint; keyword-only; optional

Index of the first track to return. Use with limit to get the next batch of tracks.

Minimum value: 0.

API default: 0.

Returns:

tracksdict[str, Any]

Page of Deezer metadata for the recommended tracks.

Sample response

{
  "data": [
    {
      "album": {
        "cover": <str>,
        "cover_big": <str>,
        "cover_medium": <str>,
        "cover_small": <str>,
        "cover_xl": <str>,
        "id": <int>,
        "md5_image": <str>,
        "title": <str>,
        "tracklist": <str>,
        "type": "album"
      },
      "artist": {
        "id": <int>,
        "name": <str>,
        "picture": <str>,
        "picture_big": <str>,
        "picture_medium": <str>,
        "picture_small": <str>,
        "picture_xl": <str>,
        "tracklist": <str>,
        "type": "artist"
      },
      "duration": <int>,
      "explicit_content_cover": <int>,
      "explicit_content_lyrics": <int>,
      "explicit_lyrics": <bool>,
      "id": <int>,
      "md5_image": <str>,
      "preview": <str>,
      "rank": <int>,
      "readable": <bool>,
      "timestamp": <int>,
      "title": <str>,
      "title_short": <str>,
      "title_version": <str>,
      "type": "track"
    }
  ],
  "next": <str>,
  "prev": <str>,
  "total": <int>
}

get_user_tracks(user_id: int | str = 'me', /, *, limit: int | None = None, offset: int | None = None) → dict[str, Any][source]¶

User > Personal Songs: Get Deezer catalog information for a user’s uploaded tracks.

User authentication

Required

User authentication: Access the user’s favorite items, playlists, and followed people.

Parameters:

user_idint or str; positional-only; default: "me"

Deezer ID of the user. If authenticated, "me" can be used in lieu of a Deezer ID for the current user.

Example: 5395005364, "5395005364", "me".

limitint; keyword-only; optional

Maximum number of tracks to return.

Minimum value: 1.

offsetint; keyword-only; optional

Index of the first track to return. Use with limit to get the next batch of tracks.

Minimum value: 0.

API default: 0.

Returns:

tracksdict[str, Any]

Page of Deezer metadata for the user’s uploaded tracks.

Sample response

{
  "data": [
    {
      "album": {
        "cover": <str>,
        "cover_big": <str>,
        "cover_medium": <str>,
        "cover_small": <str>,
        "cover_xl": <str>,
        "id": <int>,
        "md5_image": <str>,
        "title": <str>,
        "tracklist": <str>,
        "type": "album"
      },
      "artist": {
        "id": <int>,
        "name": <str>,
        "picture": <str>,
        "picture_big": <str>,
        "picture_medium": <str>,
        "picture_small": <str>,
        "picture_xl": <str>,
        "tracklist": <str>,
        "type": "artist"
      },
      "duration": <int>,
      "explicit_content_cover": <int>,
      "explicit_content_lyrics": <int>,
      "explicit_lyrics": <bool>,
      "id": <int>,
      "md5_image": <str>,
      "preview": <str>,
      "rank": <int>,
      "readable": <bool>,
      "title": <str>,
      "title_short": <str>,
      "title_version": <str>,
      "type": "track"
    }
  ],
  "next": <str>,
  "prev": <str>,
  "total": <int>
}

remove_episode_resume_point(episode_id: int | str, /) → dict[str, Any][source]¶

Episode > Bookmark: Remove a resume point for a podcast episode.

Permission

Required

manage_library permission: Manage a user’s library. Learn more.

Parameters:

episode_idint or str; positional-only

Deezer ID of the episode.

Example: 796445891, "822265072".

Returns:

statusdict[str, Any]

Whether the resume point was removed successfully.

Sample response: {'error': [], 'results': True}.

remove_saved_album(album_id: int | str, /, *, user_id: int | str = 'me') → bool[source]¶

User > Albums: Unfavorite an album.

Permissions

Required

manage_library permission: Manage a user’s library. Learn more.
delete_library permission: Delete items from a user’s library. Learn more.

Parameters:

album_idint or str; positional-only

Deezer ID of the album.

Examples: 10546890, "816455081".

user_idint or str; keyword-only; default: "me"

Deezer ID of the user. If authenticated, "me" can be used in lieu of a Deezer ID for the current user.

Example: 5395005364, "5395005364", "me".

Returns:

successbool: Whether the album was unfavorited successfully.

remove_saved_radio(radio_id: int | str, /, *, user_id: int | str = 'me') → bool[source]¶

User > Radios: Unfavorite a radio.

Permissions

Required

manage_library permission: Manage a user’s library. Learn more.
delete_library permission: Delete items from a user’s library. Learn more.

Parameters:

radio_idint or str; positional-only

Deezer ID of the radio.

Examples: 31061, "37151".

user_idint or str; keyword-only; default: "me"

Deezer ID of the user. If authenticated, "me" can be used in lieu of a Deezer ID for the current user.

Example: 5395005364, "5395005364", "me".

Returns:

successbool: Whether the radio was unfavorited successfully.

remove_saved_track(track_id: int | str, /, *, user_id: int | str = 'me') → bool[source]¶

User > Tracks: Unfavorite a track.

Permissions

Required

manage_library permission: Manage a user’s library. Learn more.
delete_library permission: Delete items from a user’s library. Learn more.

Parameters:

track_idint or str; positional-only

Deezer ID of the track.

Examples: 101602968, "3541756661".

user_idint or str; keyword-only; default: "me"

Deezer ID of the user. If authenticated, "me" can be used in lieu of a Deezer ID for the current user.

Example: 5395005364, "5395005364", "me".

Returns:

successbool: Whether the track was unfavorited successfully.

reorder_playlist_tracks(playlist_id: int | str, /, track_ids: int | str | Collection[int | str]) → Any[source]¶

Playlist > Tracks: Reorder tracks in a playlist.

Permission

Required

manage_library permission: Manage a user’s library. Learn more.

Parameters:

playlist_idint or str; positional-only

Deezer ID of the playlist.

Examples: 13651021241, "1495242491".

track_idsint, str, or Collection[int | str]

Deezer IDs of the tracks in the desired order.

Examples: 101602968, "3541756661", "101602968,3541756661", [101602968, "3541756661"].