PrivateAlbumsAPI

class minim.api.tidal.PrivateAlbumsAPI(client: APIClient, /)[source]

Bases: PrivateTIDALResourceAPI

Albums API endpoints for the private TIDAL API.

Important

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

Parameters:
clientminim.api._shared.APIClient

API client instance used to make HTTP requests.

Methods

get_album

Get TIDAL catalog information for an album.

get_album_credits

Get TIDAL catalog information for credits for an album.

get_album_item_credits

Get TIDAL catalog information for credits for the tracks and videos in an album.

get_album_items

Get TIDAL catalog information for tracks and videos in an album.

get_album_page

Get the TIDAL page layout for an album.

get_album_review

Get a review of or synopsis for an album.

get_similar_albums

Get TIDAL catalog information for similar albums.

get_user_saved_albums

Get TIDAL catalog information for albums in a user's collection.

remove_saved_albums

Remove albums from a user's collection.

save_albums

Add albums to a user's collection.
get_album(album_id: int | str, /, country_code: str | None = None) → dict[str, Any][source]

Get TIDAL catalog information for an album.

Parameters:
album_idint or str; positional-only

TIDAL ID of the album.

Examples: 46369321, "251380836".

country_codestr; optional

ISO 3166-1 alpha-2 country code. If not provided, the country associated with the current user account or IP address is used.

Example: "US".

Returns:
albumdict[str, Any]

TIDAL metadata for the album.

Sample response

{
  "adSupportedStreamReady": <bool>,
  "allowStreaming": <bool>,
  "artist": {
    "handle": <str>,
    "id": <int>,
    "name": <str>,
    "picture": <str>,
    "type": "MAIN"
  },
  "artists": [
    {
      "handle": <str>,
      "id": <int>,
      "name": <str>,
      "picture": <str>,
      "type": <str>
    }
  ],
  "audioModes": <list[str]>,
  "audioQuality": <str>,
  "copyright": <str>,
  "cover": <str>,
  "djReady": <bool>,
  "duration": <int>,
  "explicit": <bool>,
  "id": <int>,
  "mediaMetadata": {
    "tags": <list[str]>
  },
  "numberOfTracks": <int>,
  "numberOfVideos": <int>,
  "numberOfVolumes": <int>,
  "payToStream": <bool>,
  "popularity": <int>,
  "premiumStreamingOnly": <bool>,
  "releaseDate": <str>,
  "stemReady": <bool>,
  "streamReady": <bool>,
  "streamStartDate": <str>,
  "title": <str>,
  "type": "ALBUM",
  "upc": <str>,
  "upload": <bool>,
  "url": <str>,
  "version": <str>,
  "vibrantColor": <str>,
  "videoCover": <str>
}
get_album_credits(album_id: int | str, /, country_code: str | None = None) → list[dict[str, Any]][source]

Get TIDAL catalog information for credits for an album.

Parameters:
album_idint or str; positional-only

TIDAL ID of the album.

Examples: 46369321, "251380836".

country_codestr; optional

ISO 3166-1 alpha-2 country code. If not provided, the country associated with the current user account or IP address is used.

Example: "US".

Returns:
creditsdict[str, Any]

TIDAL metadata for the album’s credits.

Sample response

[
  {
    "contributors": [
      {
        "id": <int>,
        "name": <str>
      }
    ],
    "type": <str>
  }
]
get_album_item_credits(album_id: int | str, /, country_code: str | None = None, *, limit: int | None = None, offset: int | None = None) → dict[str, Any][source]

Get TIDAL catalog information for credits for the tracks and videos in an album.

Parameters:
album_idint or str; positional-only

TIDAL ID of the album.

Examples: 46369321, "251380836".

country_codestr; optional

ISO 3166-1 alpha-2 country code. If not provided, the country associated with the current user account or IP address is used.

Example: "US".

limitint; keyword-only; optional

Maximum number of credits to return.

Valid range: 1 to 100.

API default: 10.

offsetint; keyword-only; optional

Index of the first credit to return. Use with limit to get the next batch of credits.

Minimum value: 0.

API default: 0.

Returns:
creditsdict[str, Any]

Page of TIDAL metadata for the credits for the album’s tracks and videos.

Sample response

{
  "items": [
    {
      "credits": [
        {
          "contributors": [
            {
              "name": <str>
            }
          ],
          "type": <str>
        }
      ],
      "item": {
        "accessType": <str>,
        "adSupportedStreamReady": <bool>,
        "album": {
          "cover": <str>,
          "id": <int>,
          "title": <str>,
          "vibrantColor": <str>,
          "videoCover": <str>
        },
        "allowStreaming": <bool>,
        "artist": {
          "handle": <str>,
          "id": <int>,
          "name": <str>,
          "picture": <str>,
          "type": "MAIN"
        },
        "artists": [
          {
            "handle": <str>,
            "id": <int>,
            "name": <str>,
            "picture": <str>,
            "type": <str>
          }
        ],
        "audioModes": <list[str]>,
        "audioQuality": <str>,
        "bpm": <int>,
        "copyright": <str>,
        "djReady": <bool>,
        "duration": <int>,
        "editable": <bool>,
        "explicit": <bool>,
        "id": <int>,
        "isrc": <str>,
        "key": <str>,
        "keyScale": <str>,
        "mediaMetadata": {
          "tags": <list[str]>
        },
        "mixes": {
          "TRACK_MIX": <str>
        },
        "payToStream": <bool>,
        "peak": <float>,
        "popularity": <int>,
        "premiumStreamingOnly": <bool>,
        "replayGain": <float>,
        "spotlighted": <bool>,
        "stemReady": <bool>,
        "streamReady": <bool>,
        "streamStartDate": <str>,
        "title": <str>,
        "trackNumber": <int>,
        "upload": <bool>,
        "url": <str>,
        "version": <str>,
        "volumeNumber": <int>
      },
      "type": "track"
    },
    {
      "credits": [
        {
          "contributors": [
            {
              "name": <str>
            }
          ],
          "type": <str>
        }
      ],
      "item": {
        "adSupportedStreamReady": <bool>,
        "adsPrePaywallOnly": <bool>,
        "adsUrl": <str>,
        "album": {
          "cover": <str>,
          "id": <int>,
          "title": <str>,
          "vibrantColor": <str>,
          "videoCover": <str>
        },
        "allowStreaming": <bool>,
        "artist": {
          "handle": <str>,
          "id": <int>,
          "name": <str>,
          "picture": <str>,
          "type": "MAIN"
        },
        "artists": [
          {
            "handle": <str>,
            "id": <int>,
            "name": <str>,
            "picture": <str>,
            "type": <str>
          }
        ],
        "djReady": <bool>,
        "duration": <int>,
        "explicit": <bool>,
        "id": <int>,
        "imageId": <str>,
        "imagePath": <str>,
        "popularity": <int>,
        "quality": <str>,
        "releaseDate": <str>,
        "stemReady": <bool>,
        "streamReady": <bool>,
        "streamStartDate": <str>,
        "title": <str>,
        "trackNumber": <int>,
        "type": "Music Video",
        "vibrantColor": <str>,
        "volumeNumber": <int>
      },
      "type": "video"
    }
  ],
  "limit": <int>,
  "offset": <int>,
  "totalNumberOfItems": <int>
}
get_album_items(album_id: int | str, /, country_code: str | None = None, *, limit: int | None = None, offset: int | None = None) → dict[str, Any][source]

Get TIDAL catalog information for tracks and videos in an album.

Parameters:
album_idint or str; positional-only

TIDAL ID of the album.

Examples: 46369321, "251380836".

country_codestr; optional

ISO 3166-1 alpha-2 country code. If not provided, the country associated with the current user account or IP address is used.

Example: "US".

limitint; keyword-only; optional

Maximum number of items to return.

Valid range: 1 to 100.

API default: 10.

offsetint; keyword-only; optional

Index of the first item to return. Use with limit to get the next batch of items.

Minimum value: 0.

API default: 0.

Returns:
itemsdict[str, Any]

Page of TIDAL metadata for the album’s tracks and videos.

Sample response

{
  "items": [
    {
      "item": {
        "accessType": <str>,
        "adSupportedStreamReady": <bool>,
        "album": {
          "cover": <str>,
          "id": <int>,
          "title": <str>,
          "vibrantColor": <str>,
          "videoCover": <str>
        },
        "allowStreaming": <bool>,
        "artist": {
          "handle": <str>,
          "id": <int>,
          "name": <str>,
          "picture": <str>,
          "type": "MAIN"
        },
        "artists": [
          {
            "handle": <str>,
            "id": <int>,
            "name": <str>,
            "picture": <str>,
            "type": <str>
          }
        ],
        "audioModes": <list[str]>,
        "audioQuality": <str>,
        "bpm": <int>,
        "copyright": <str>,
        "djReady": <bool>,
        "duration": <int>,
        "editable": <bool>,
        "explicit": <bool>,
        "id": <int>,
        "isrc": <str>,
        "key": <str>,
        "keyScale": <str>,
        "mediaMetadata": {
          "tags": <list[str]>
        },
        "mixes": {
          "TRACK_MIX": <str>
        },
        "payToStream": <bool>,
        "peak": <float>,
        "popularity": <int>,
        "premiumStreamingOnly": <bool>,
        "replayGain": <float>,
        "spotlighted": <bool>,
        "stemReady": <bool>,
        "streamReady": <bool>,
        "streamStartDate": <str>,
        "title": <str>,
        "trackNumber": <int>,
        "upload": <bool>,
        "url": <str>,
        "version": <str>,
        "volumeNumber": <int>
      },
      "type": "track"
    },
    {
      "item": {
        "adSupportedStreamReady": <bool>,
        "adsPrePaywallOnly": <bool>,
        "adsUrl": <str>,
        "album": {
          "cover": <str>,
          "id": <int>,
          "title": <str>,
          "vibrantColor": <str>,
          "videoCover": <str>
        },
        "allowStreaming": <bool>,
        "artist": {
          "handle": <str>,
          "id": <int>,
          "name": <str>,
          "picture": <str>,
          "type": "MAIN"
        },
        "artists": [
          {
            "handle": <str>,
            "id": <int>,
            "name": <str>,
            "picture": <str>,
            "type": <str>
          }
        ],
        "djReady": <bool>,
        "duration": <int>,
        "explicit": <bool>,
        "id": <int>,
        "imageId": <str>,
        "imagePath": <str>,
        "popularity": <int>,
        "quality": <str>,
        "releaseDate": <str>,
        "stemReady": <bool>,
        "streamReady": <bool>,
        "streamStartDate": <str>,
        "title": <str>,
        "trackNumber": <int>,
        "type": "Music Video",
        "vibrantColor": <str>,
        "volumeNumber": <int>
      },
      "type": "video"
    }
  ],
  "limit": <int>,
  "offset": <int>,
  "totalNumberOfItems": <int>
}
get_album_page(album_id: int | str, /, country_code: str | None = None, *, device_type: str = 'BROWSER', locale: str | None = None) → dict[str, Any][source]

Get the TIDAL page layout for an album.

Parameters:
album_idint or str; positional-only

TIDAL ID of the album.

Examples: 46369321, "251380836".

country_codestr; optional

ISO 3166-1 alpha-2 country code. If not provided, the country associated with the current user account or IP address is used.

Example: "US".

device_typestr; keyword-only; default: "BROWSER"

Device type.

Valid values:

  • "BROWSER" – Web browser.

  • "DESKTOP" – Desktop TIDAL application.

  • "PHONE" – Mobile TIDAL application.

  • "TV" – Smart TV TIDAL application.

localestr; keyword-only; optional

IETF BCP 47 language tag.

API default: "en_US" – English (U.S.).

Returns:
pagedict[str, Any]

Layout for the album page.

Sample response

{
  "id": <str>,
  "rows": [
    {
      "modules": [
        {
          "album": {
            "allowStreaming": <bool>,
            "artists": [
              {
                "contributionLinkUrl": <str>,
                "handle": <str>,
                "id": <int>,
                "name": <str>,
                "picture": <str>,
                "type": <str>,
                "userId": <int>
              }
            ],
            "audioModes": <list[str]>,
            "audioQuality": <str>,
            "copyright": <str>,
            "cover": <str>,
            "duration": <int>,
            "explicit": <bool>,
            "id": <int>,
            "mediaMetadata": {
              "tags": <list[str]>
            },
            "numberOfTracks": <int>,
            "numberOfVideos": <int>,
            "numberOfVolumes": <int>,
            "payToStream": <bool>,
            "popularity": <int>,
            "releaseDate": <str>,
            "streamReady": <bool>,
            "streamStartDate": <str>,
            "title": <str>,
            "type": <str>,
            "upload": <bool>,
            "url": <str>,
            "version": <str>,
            "videoCover": <str>
          },
          "credits": {
            "items": [
              {
                "contributors": [
                  {
                    "id": <int>,
                    "name": <str>
                  }
                ],
                "type": <str>
              }
            ]
          },
          "description": <str>,
          "id": <str>,
          "playbackControls": [
            {
              "icon": <str>,
              "playbackMode": <str>,
              "shuffle": <bool>,
              "targetModuleId": <str>,
              "title": <str>
            }
          ],
          "preTitle": <str>,
          "review": {
            "source": <str>,
            "text": <str>
          },
          "title": <str>,
          "type": "ALBUM_HEADER",
          "width": <int>
        }
      ]
    },
    {
      "modules": [
        {
          "copyright": <str>,
          "description": <str>,
          "id": <str>,
          "listFormat": <str>,
          "pagedList": {
            "dataApiPath": <str>,
            "items": [
              {
                "item": {
                  "accessType": <str>,
                  "adSupportedStreamReady": <bool>,
                  "album": {
                    "cover": <str>,
                    "id": <int>,
                    "releaseDate": <str>,
                    "title": <str>,
                    "url": <str>,
                    "vibrantColor": <str>,
                    "videoCover": <str>
                  },
                  "allowStreaming": <bool>,
                  "artists": [
                    {
                      "handle": <str>,
                      "id": <int>,
                      "name": <str>,
                      "picture": <str>,
                      "type": <str>,
                      "userId": <int>
                    }
                  ],
                  "audioModes": <list[str]>,
                  "audioQuality": <str>,
                  "djReady": <bool>,
                  "doublePopularity": <float>,
                  "duration": <int>,
                  "editable": <bool>,
                  "explicit": <bool>,
                  "id": <int>,
                  "mediaMetadata": {
                    "tags": <list[str]>
                  },
                  "mixes": {
                    "TRACK_MIX": <str>
                  },
                  "payToStream": <bool>,
                  "popularity": <int>,
                  "replayGain": <float>,
                  "spotlighted": <bool>,
                  "stemReady": <bool>,
                  "streamReady": <bool>,
                  "streamStartDate": <str>,
                  "title": <str>,
                  "trackNumber": <int>,
                  "upload": <bool>,
                  "url": <str>,
                  "version": <str>,
                  "volumeNumber": <int>
                },
                "type": "track"
              }
            ],
            "limit": <int>,
            "offset": <int>,
            "totalNumberOfItems": <int>
          },
          "playButton": <bool>,
          "preTitle": <str>,
          "quickPlay": <bool>,
          "releaseDate": <str>,
          "showMore": {
            "apiPath": <str>,
            "title": <str>
          },
          "shuffleButton": <bool>,
          "supportsPaging": <bool>,
          "title": <str>,
          "type": "ALBUM_ITEMS",
          "width": <int>
        }
      ]
    },
    {
      "modules": [
        {
          "description": <str>,
          "header": <str>,
          "id": <str>,
          "layout": <str>,
          "listFormat": <str>,
          "pagedList": {
            "dataApiPath": <str>,
            "items": [
              {
                "allowStreaming": <bool>,
                "artists": [
                  {
                    "contributionLinkUrl": <str>,
                    "handle": <str>,
                    "id": <int>,
                    "name": <str>,
                    "picture": <str>,
                    "type": <str>,
                    "userId": <int>
                  }
                ],
                "audioModes": <list[str]>,
                "audioQuality": <str>,
                "cover": <str>,
                "duration": <int>,
                "explicit": <bool>,
                "id": <int>,
                "mediaMetadata": {
                  "tags": <list[str]>
                },
                "numberOfTracks": <int>,
                "numberOfVideos": <int>,
                "payToStream": <bool>,
                "releaseDate": <str>,
                "streamReady": <bool>,
                "streamStartDate": <str>,
                "title": <str>,
                "upload": <bool>,
                "url": <str>,
                "vibrantColor": <str>,
                "videoCover": <str>
              }
            ],
            "limit": <int>,
            "offset": <int>,
            "totalNumberOfItems": <int>
          },
          "preTitle": <str>,
          "quickPlay": <bool>,
          "scroll": <str>,
          "showMore": {
            "apiPath": <str>,
            "title": <str>
          },
          "supportsPaging": <bool>,
          "title": <str>,
          "type": "ALBUM_LIST",
          "width": <int>
        }
      ]
    },
    {
      "modules": [
        {
          "description": <str>,
          "header": <str>,
          "id": <str>,
          "layout": <str>,
          "pagedList": {
            "dataApiPath": <str>,
            "items": [
              {
                "artistRoles": [
                  {
                    "category": <str>,
                    "categoryId": <int>
                  }
                ],
                "artistTypes": <list[str]>,
                "id": <int>,
                "mixes": {
                  "ARTIST_MIX": <str>
                },
                "name": <str>,
                "picture": <str>,
                "selectedAlbumCoverFallback": None
              }
            ],
            "limit": <int>,
            "offset": <int>,
            "totalNumberOfItems": <int>
          },
          "preTitle": <str>,
          "quickPlay": <bool>,
          "scroll": <str>,
          "showMore": {
            "apiPath": <str>,
            "title": <str>
          },
          "supportsPaging": <bool>,
          "title": <str>,
          "type": "ARTIST_LIST",
          "width": <int>
        }
      ]
    }
  ],
  "selfLink": <str>,
  "title": <str>
}
get_album_review(album_id: int | str, /, country_code: str | None = None) → dict[str, str][source]

Get a review of or synopsis for an album.

Parameters:
album_idint or str; positional-only

TIDAL ID of the album.

Examples: 46369321, "251380836".

country_codestr; optional

ISO 3166-1 alpha-2 country code. If not provided, the country associated with the current user account or IP address is used.

Example: "US".

Returns:
reviewdict[str, Any]

Metadata for the album’s review or synopsis.

Sample response

{
  "lastUpdated": <str>,
  "source": <str>,
  "summary": <str>,
  "text": <str>,
}
get_similar_albums(album_id: int | str, /, country_code: str | None = None, *, limit: int | None = None, offset: int | None = None) → dict[str, Any][source]

Get TIDAL catalog information for similar albums.

Parameters:
album_idint or str; positional-only

TIDAL ID of the album.

Examples: 46369321, "251380836".

country_codestr; optional

ISO 3166-1 alpha-2 country code. If not provided, the country associated with the current user account or IP address is used.

Example: "US".

limitint; keyword-only; optional

Maximum number of albums to return.

Valid range: 1 to 100.

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 TIDAL metadata for the similar albums.

Sample response

{
  "items": [
    {
      "adSupportedStreamReady": <bool>,
      "allowStreaming": <bool>,
      "artist": {
        "handle": <str>,
        "id": <int>,
        "name": <str>,
        "picture": <str>,
        "type": "MAIN"
      },
      "artists": [
        {
          "handle": <str>,
          "id": <int>,
          "name": <str>,
          "picture": <str>,
          "type": <str>
        }
      ],
      "audioModes": <list[str]>,
      "audioQuality": <str>,
      "copyright": <str>,
      "cover": <str>,
      "djReady": <bool>,
      "duration": <int>,
      "explicit": <bool>
      "id": <int>,
      "mediaMetadata": {
        "tags": <list[str]>
      },
      "numberOfTracks": <int>,
      "numberOfVideos": <int>,
      "numberOfVolumes": <int>,
      "payToStream": <bool>,
      "popularity": <int>,
      "premiumStreamingOnly": <bool>,
      "releaseDate": <str>,
      "stemReady": <bool>,
      "streamReady": <bool>,
      "streamStartDate": <str>,
      "title": <str>,
      "type": "ALBUM",
      "upc": <str>,
      "upload": <bool>,
      "url": <str>,
      "version": <str>,
      "vibrantColor": <str>,
      "videoCover": <str>
    }
  ],
  "limit": <int>,
  "offset": <int>,
  "source": <str>,
  "totalNumberOfItems": <int>
}
get_user_saved_albums(user_id: int | str | None = None, /, country_code: str | None = None, *, limit: int | None = None, offset: int | None = None, sort_by: str | None = None, descending: bool | None = None) → dict[str, Any][source]

Get TIDAL catalog information for albums in a user’s collection.

User authentication

User authentication

Access and manage the user’s collection.

Parameters:
user_idint or str; positional-only; optional

TIDAL ID of the user. If not specified, the current user’s TIDAL ID is used.

country_codestr; optional

ISO 3166-1 alpha-2 country code. If not provided, the country associated with the current user account or IP address is used.

Example: "US".

limitint; keyword-only; optional

Maximum number of albums to return.

Valid range: 1 to 100.

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.

sort_bystr; keyword-only; optional

Field to sort the albums by.

Valid values:

  • "DATE" - Date added.

  • "NAME" - Album name.

API default: "DATE".

descendingbool; keyword-only; optional

Whether to sort in descending order.

API default: False.

Returns:
albumsdict[str, Any]

Page of TIDAL metadata for the albums in the user’s collection.

Sample response

{
  "items": [
    {
      "created": <str>,
      "item": {
        "adSupportedStreamReady": <bool>,
        "allowStreaming": <bool>,
        "artist": {
          "handle": <str>,
          "id": <int>,
          "name": <str>,
          "picture": <str>,
          "type": <str>
        },
        "artists": [
          {
            "handle": <str>,
            "id": <int>,
            "name": <str>,
            "picture": <str>,
            "type": <str>
          }
        ],
        "audioModes": <list[str]>,
        "audioQuality": <str>,
        "copyright": <str>,
        "cover": <str>,
        "djReady": <bool>,
        "duration": <int>,
        "explicit": <bool>
        "id": <int>,
        "mediaMetadata": {
          "tags": <list[str]>
        },
        "numberOfTracks": <int>,
        "numberOfVideos": <int>,
        "numberOfVolumes": <int>,
        "payToStream": <bool>,
        "popularity": <int>,
        "premiumStreamingOnly": <bool>,
        "releaseDate": <str>,
        "stemReady": <bool>,
        "streamReady": <bool>,
        "streamStartDate": <str>,
        "title": <str>,
        "type": "ALBUM",
        "upc": <str>,
        "upload": <bool>,
        "url": <str>,
        "version": <str>,
        "vibrantColor": <str>,
        "videoCover": <str>
      }
  ],
  "limit": <int>,
  "offset": <int>,
  "totalNumberOfItems": <int>
}
remove_saved_albums(album_ids: int | str | Collection[int | str], /, user_id: int | str | None = None) → None[source]

Remove albums from a user’s collection.

User authentication

User authentication

Access and manage the user’s collection.

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

TIDAL IDs of the albums.

Examples: 46369321, "251380836", "46369321,251380836", [46369321, "251380836"].

user_idint or str; optional

TIDAL ID of the user. If not specified, the current user’s TIDAL ID is used.

save_albums(album_ids: int | str | Collection[int | str], /, user_id: int | str | None = None, country_code: str | None = None, *, missing_ok: bool | None = None) → None[source]

Add albums to a user’s collection.

User authentication

User authentication

Access and manage the user’s collection.

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

TIDAL IDs of the albums.

Examples: 46369321, "251380836", "46369321,251380836", [46369321, "251380836"].

user_idint or str; optional

TIDAL ID of the user. If not specified, the current user’s TIDAL ID is used.

country_codestr; optional

ISO 3166-1 alpha-2 country code. If not provided, the country associated with the current user account or IP address is used.

Example: "US".

on_missingstr; keyword-only; optional

Behavior when the albums to be favorited cannot be found in the TIDAL catalog.

API default: "FAIL".