PlaylistsAPI

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

Bases: DeezerResourceAPI

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

follow_playlists

User > Playlists: Favorite one or more playlists.

get_playlist

Playlist: Get Deezer catalog information for a playlist.

get_playlist_fans

Playlist > Fans: Get Deezer profile information for fans of a playlist.

get_playlist_radio_tracks

Playlist > Radio: Get Deezer catalog information for algorithmically selected tracks in a playlist's radio.

get_playlist_tracks

Playlist > Tracks: Get Deezer catalog information for tracks in a playlist.

get_top_playlists

Chart > Playlists: Get Deezer catalog information for the top playlists on Deezer.

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_top_playlists

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

mark_playlist_seen

Playlist > Seen: Mark a Deezer playlist as seen.

reorder_playlist_tracks

Playlist > Tracks: Reorder tracks in a playlist.

unfollow_playlist

User > Playlists: Unfavorite a playlist.

update_playlist_details

Playlist: Update the details of a playlist.
add_playlist_tracks(playlist_id: int | str, /, track_ids: int | str | Collection[int | str]) → bool[source]

Playlist > Tracks: Add tracks to a playlist.

Permission

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) → dict[str, int][source]

User > Playlists: Create a playlist.

Permission

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

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.

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

User > Playlists: Favorite one or more playlists.

Permission

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.

get_playlist(playlist_id: int | str, /, *, limit: int | None = None, offset: int | None = None) → dict[str, Any][source]

Playlist: Get Deezer catalog information for a playlist.

Parameters:
playlist_idint or str; positional-only

Deezer ID of the playlist.

Examples: 13651021241, "1495242491".

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:
playlistdict[str, Any]

Deezer metadata for the playlist and its tracks.

Sample response

{
  "add_date": <str>,
  "checksum": <str>,
  "collaborative": <bool>,
  "creation_date": <str>,
  "creator": {
    "id": <int>,
    "name": <str>,
    "tracklist": <str>,
    "type": "user"
  },
  "description": <str>,
  "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>,
  "share": <str>,
  "title": <str>,
  "tracklist": <str>,
  "tracks": {
    "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",
          "upc": <str>
        },
        "artist": {
          "id": <int>,
          "link": <str>,
          "name": <str>,
          "tracklist": <str>,
          "type": "artist"
        },
        "duration": <int>,
        "explicit_content_cover": <int>,
        "explicit_content_lyrics": <int>,
        "explicit_lyrics": <bool>,
        "id": <int>,
        "isrc": <str>,
        "link": <str>,
        "md5_image": <str>,
        "preview": <str>,
        "rank": <int>,
        "readable": <bool>,
        "time_add": <int>,
        "title": "<str>,
        "title_short": <str>,
        "title_version": <str>,
        "type": "track"
      }
    ]
  },
  "type": "playlist"
}
get_playlist_fans(playlist_id: int | str, /, *, limit: int | None = None, offset: int | None = None) → dict[str, Any][source]

Playlist > Fans: Get Deezer profile information for fans of a playlist.

Parameters:
playlist_idint or str; positional-only

Deezer ID of the playlist.

Examples: 13651021241, "1495242491".

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 playlist’s fans.

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_playlist_radio_tracks(playlist_id: int | str, /) → dict[str, Any][source]

Playlist > Radio: Get Deezer catalog information for algorithmically selected tracks in a playlist’s radio.

Parameters:
playlist_idint or str; positional-only

Deezer ID of the playlist.

Examples: 13651021241, "1495242491".

Returns:
tracksdict[str, Any]

Deezer metadata for the tracks in the playlist’s radio.

Sample response

{
  "data": [
    {
      "album": {
        "id": <int>,
        "md5_image": <str>,
        "title": <str>,
        "tracklist": <str>,
        "type": "album"
      },
      "artist": {
        "id": <int>,
        "link": <str>,
        "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>,
      "isrc": <str>,
      "link": <str>,
      "md5_image": <str>,
      "preview": <str>,
      "rank": <int>,
      "title": <str>,
      "title_short": <str>,
      "title_version": <str>,
      "type": "track"
    }
  ]
}
get_playlist_tracks(playlist_id: int | str, /, *, limit: int | None = None, offset: int | None = None) → dict[str, Any][source]

Playlist > Tracks: Get Deezer catalog information for tracks in a playlist.

Parameters:
playlist_idint or str; positional-only

Deezer ID of the playlist.

Examples: 13651021241, "1495242491".

limitint; keyword-only; optional

Maximum number of tracks to return.

Minimum value: 1.

API default: 25.

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 playlist’s 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",
        "upc": <str>,
      },
      "artist": {
        "id": <int>,
        "link": <str>,
        "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>,
      "isrc": <str>,
      "link": <str>,
      "md5_image": <str>,
      "preview": <str>,
      "rank": <int>,
      "readable": <bool>,
      "time_add": <int>,
      "title": <str>,
      "title_short": <str>,
      "title_version": <str>,
      "type": "track"
    }
  ],
  "prev": <str>,
  "next": <str>,
  "total": <int>
}
get_top_playlists(*, limit: int | None = None, offset: int | None = None) → dict[str, Any][source]

Chart > Playlists: Get Deezer catalog information for the top playlists on Deezer.

Parameters:
limitint; keyword-only; optional

Maximum number of playlists to return.

Minimum value: 1.

API default: 10.

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 top playlists.

Sample response

{
  "data": [
    {
      "add_date": <str>,
      "checksum": <str>,
      "creation_date": <str>,
      "id": <int>,
      "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",
      "user": {
        "id": <int>,
        "name": <str>,
        "tracklist": <str>,
        "type": "user"
      }
    }
  ],
  "prev": <str>,
  "next": <str>,
  "total": <int>
}
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

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

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

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>
}
mark_playlist_seen(playlist_id: int | str, /) → bool[source]

Playlist > Seen: Mark a Deezer playlist as seen.

Parameters:
playlist_idint or str; positional-only

Deezer ID of the playlist.

Examples: 13651021241, "1495242491".

Returns:
successbool

Whether the playlist was successfully marked as seen.

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

Playlist > Tracks: Reorder tracks in a playlist.

Permission

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"].

See also

get_playlist_tracks() – Get Deezer IDs of the tracks in the playlist.

Returns:
successbool

Whether the tracks were reordered successfully.

unfollow_playlist(playlist_id: int | str, /, *, user_id: int | str = 'me') → bool[source]

User > Playlists: Unfavorite a playlist.

Permissions

manage_library permission

Manage a user’s library. Learn more.

delete_library permission

Delete items from a user’s library. Learn more.

Parameters:
playlist_idsint or 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 playlist was unfavorited successfully.

update_playlist_details(playlist_id: int | str, /, *, name: str | None = None, description: str | None = None, public: bool | None = None, collaborative: bool | None = None) → bool[source]

Playlist: Update the details of a playlist.

Permission

manage_library permission

Manage a user’s library. Learn more.

Important

At least one of name, description, public, or collaborative must be specified.

Parameters:
playlist_idint or str; positional-only

Deezer ID of the playlist.

Examples: 13651021241, "1495242491".

namestr; keyword-only; optional

New playlist name.

descriptionstr; keyword-only; optional

New playlist description.

publicbool; keyword-only; optional

Whether the playlist is displayed on the current user’s profile.

collaborativebool; keyword-only; optional

Whether other users can modify the playlist.

Note

collaborative=True can only be set on public playlists.

Returns:
successbool

Whether the playlist details were updated successfully.