AlbumsAPI¶

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

Bases: DeezerResourceAPI

Albums 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

`get_album`	Album: Get Deezer catalog information for an album.
`get_album_fans`	Album > Fans: Get Deezer profile information for fans of an album.
`get_album_tracks`	Album > Tracks: Get Deezer catalog information for tracks on an album.
`get_top_albums`	Chart > Albums: Get Deezer catalog information for the top albums on Deezer.
`get_user_album_recommendations`	User > Recommendations > Albums: Get Discogs catalog information for albums recommended for a user.
`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_top_albums`	User > Charts > Albums: Get Deezer catalog information for a user's top albums on Deezer.
`remove_saved_album`	User > Albums: Unfavorite an album.
`save_albums`	User > Albums: Favorite one or more albums.

get_album(album_id: int | str, /, *, limit: int | None = None, offset: int | None = None) → dict[str, Any][source]¶

Album: Get Deezer catalog information for an album.

Parameters:

album_idint or str; positional-only

Deezer ID of the album.

Examples: 10546890, "816455081".

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:

albumdict[str, Any]

Deezer metadata for the album.

Sample response

{
  "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>,
  "contributors": [
    {
      "id": <int>,
      "link": <str>,
      "name": <str>,
      "picture": <str>,
      "picture_big": <str>,
      "picture_medium": <str>,
      "picture_small": <str>,
      "picture_xl": <str>,
      "radio": <bool>,
      "role": <str>,
      "share": <str>,
      "tracklist": <str>,
      "type": "artist"
    }
  ],
  "cover": <str>,
  "cover_big": <str>,
  "cover_medium": <str>,
  "cover_small": <str>,
  "cover_xl": <str>,
  "duration": <int>,
  "explicit_content_cover": <int>,
  "explicit_content_lyrics": <int>,
  "explicit_lyrics": <bool>,
  "fans": <int>,
  "genre_id": <int>,
  "genres": {
    "data": [
      {
        "id": <int>,
        "name": <str>,
        "picture": <str>,
        "type": "genre"
      }
    ]
  },
  "id": <int>,
  "label": <str>,
  "link": <str>,
  "md5_image": <str>,
  "nb_tracks": <int>,
  "record_type": <str>,
  "release_date": <str>,
  "share": <str>,
  "title": <str>,
  "tracklist": <str>,
  "tracks": {
    "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>,
          "tracklist": <str>,
          "type": "artist"
        },
        "duration": <int>,
        "explicit_content_cover": <int>,
        "explicit_content_lyrics": <int>,
        "explicit_lyrics": <bool>,
        "id": <int>,
        "link": <str>,
        "md5_image": <str>,
        "preview": <str>,
        "rank": <int>,
        "readable": <bool>,
        "title": <str>,
        "title_short": <str>,
        "title_version": <str>,
        "type": "track"
      }
    ]
  },
  "type": "album",
  "upc": <str>
}

get_album_fans(album_id: int | str, /, *, limit: int | None = None, offset: int | None = None) → dict[str, Any][source]¶

Album > Fans: Get Deezer profile information for fans of an album.

Parameters:

album_idint or str; positional-only

Deezer ID of the album.

Examples: 10546890, "816455081".

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 album’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_album_tracks(album_id: int | str, /, *, limit: int | None = None, offset: int | None = None) → dict[str, Any][source]¶

Album > Tracks: Get Deezer catalog information for tracks on an album.

Parameters:

album_idint or str; positional-only

Deezer ID of the album.

Examples: 10546890, "816455081".

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 album’s tracks.

Sample response

{
  "data": [
    {
      "artist": {
        "id": <int>,
        "name": <str>,
        "tracklist": <str>,
        "type": "artist"
      },
      "disk_number": <int>,
      "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>,
      "title": <str>,
      "title_short": <str>,
      "title_version": <str>,
      "track_position": <int>,
      "type": "track"
    }
  ],
  "next": <str>,
  "total": <int>
}

get_top_albums(*, limit: int | None = None, offset: int | None = None) → dict[str, Any][source]¶

Chart > Albums: Get Deezer catalog information for the top albums on Deezer.

Parameters:

limitint; keyword-only; optional

Maximum number of albums to return.

Minimum value: 1.

API default: 10.

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

Sample response

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

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

remove_saved_album(album_id: int | str, /, *, user_id: int | str = 'me') → dict[str, str][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.

save_albums(album_ids: int | str | Collection[int | str], /, *, user_id: int | str = 'me') → dict[str, str][source]¶

User > Albums: Favorite one or more albums.

Permission

Required

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

Parameters:

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

Deezer IDs of the albums.

Examples: 10546890, "816455081", "10546890,816455081", [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 albums were favorited successfully.