AlbumsAPI¶
- class minim.api.tidal.AlbumsAPI(client: APIClient, /)[source]¶
Bases:
TIDALResourceAPIAlbums API endpoints for the TIDAL API.
Important
This class is managed by
TIDALAPIClientand should not be instantiated directly.- Parameters:
- clientminim.api._shared.APIClient
API client instance used to make HTTP requests.
Methods
Albums > Get Artists Relationship: Get TIDAL catalog information for the artists of an album.
User Collection Albums > Get User Album Collection: Get TIDAL catalog information for a user album collection.
Albums > Get Cover Art Relationship: Get TIDAL catalog information for the cover art of an album.
Albums > Get Items Relationship: Get TIDAL catalog information for tracks and videos on an album.
Albums > Get Owners Relationship: Get TIDAL profile information for owners of an album resource.
Albums > Get Providers Relationship: Get TIDAL catalog information for the providers of an album.
Albums > Get Usage Rules Relationship: Get TIDAL catalog information for the usage rules for an album.
Albums > Get Single Album: Get TIDAL catalog information for an album․ Albums > Get Multiple Albums: Get TIDAL catalog information for multiple albums.
Albums > Get Similar Albums Relationship: Get TIDAL catalog information for similar albums.
User Collection Albums > Get Items Relationship: Get TIDAL catalog information for albums in a user collection․ User Collections > Get Albums Relationship: Get TIDAL catalog information for albums in a user's collection.
User Collection Albums > Delete from Items Relationship: Remove albums from a user collection․ User Collections > Delete from Albums Relationship: Remove albums from a user's collection.
User Collection Albums > Add to Items Relationship: Add albums to a user collection․ User Collections > Add to Albums Relationship: Add albums to a user's collection.
Search Results > Get Albums Relationship: Search for albums in the TIDAL catalog.
- get_album_artists(album_id: int | str, /, country_code: str | None = None, *, include_metadata: bool = False, cursor: str | None = None, share_code: str | None = None) dict[str, Any][source]¶
Albums > Get Artists Relationship: Get TIDAL catalog information for the artists of 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.
Example:
"US".- include_metadatabool; keyword-only; default:
False Whether to include metadata for the album artists.
- cursorstr; keyword-only; optional
Cursor for fetching the next page of results.
Example:
"3nI1Esi".- share_codestr; keyword-only; optional
Share code that grants access to unlisted resources.
- Returns:
- artistsdict[str, Any]
Page of TIDAL metadata for the album artists.
Sample response
{ "data": [ { "id": <str>, "type": "artists" } ], "included": [ { "attributes": { "contributionsEnabled": <bool>, "externalLinks": [ { "href": <str>, "meta": { "type": <str> } } ], "name": <str>, "popularity": <float>, "spotlighted": <bool> }, "id": <str>, "relationships": { "albums": { "links": { "self": <str> } }, "biography": { "links": { "self": <str> } }, "followers": { "links": { "self": <str> } }, "following": { "links": { "self": <str> } }, "owners": { "links": { "self": <str> } }, "profileArt": { "links": { "self": <str> } }, "radio": { "links": { "self": <str> } }, "roles": { "links": { "self": <str> } }, "similarArtists": { "links": { "self": <str> } }, "trackProviders": { "links": { "self": <str> } }, "tracks": { "links": { "self": <str> } }, "videos": { "links": { "self": <str> } } }, "type": "artists" } ], "links": { "meta": { "nextCursor": <str> }, "next": <str>, "self": <str> } }
- get_album_collection(collection_id: str | None = None, /, *, country_code: str | None = None, locale: str | None = None, expand: str | Collection[str] | None = None) dict[str, Any][source]¶
User Collection Albums > Get User Album Collection: Get TIDAL catalog information for a user album collection.
Authorization scope
collection.readscopeRead access to a user’s collection.
- Parameters:
- collection_idstr; positional-only; optional
TIDAL ID of the user collection. If authenticated,
"me"can be used in lieu of a TIDAL ID for the current user’s collection. If not specified,"me"is used.- country_codestr; keyword-only; optional
ISO 3166-1 alpha-2 country code.
Example:
"US".- localestr; keyword-only; optional
IETF BCP 47 language tag.
- expandstr or Collection[str]; keyword-only; optional
Related resources to include metadata for in the response.
Valid values:
"items","owners".Examples:
"items",["items", "owners"].
- Returns:
- collectiondict[str, Any]
TIDAL metadata for the user album collection.
Sample response
{ "data": { "attributes": {}, "id": <str>, "relationships": { "items": { "data": [ { "id": <str>, "meta": { "addedAt": <str> }, "type": "albums" } ], "links": { "self": <str> } }, "owners": { "data": [ { "id": <str>, "type": "users" } ], "links": { "self": <str> } } }, "type": "userCollectionAlbums" }, "included": [ { "attributes": { "accessType": <str>, "albumType": <str>, "availability": <list[str]>, "barcodeId": <str>, "copyright": { "text": <str> }, "duration": <str>, "explicit": <bool>, "externalLinks": [ { "href": <str>, "meta": { "type": <str> } } ], "mediaTags": <list[str]>, "numberOfItems": <int>, "numberOfVolumes": <int>, "popularity": <float>, "releaseDate": <str>, "title": <str>, "type": <str> }, "id": <str>, "relationships": { "artists": { "links": { "self": <str> } }, "coverArt": { "links": { "self": <str> } }, "genres": { "links": { "self": <str> } }, "items": { "links": { "self": <str> } }, "owners": { "links": { "self": <str> } }, "providers": { "links": { "self": <str> } }, "similarAlbums": { "links": { "self": <str> } }, "suggestedCoverArts": { "links": { "self": <str> } } }, "type": "albums" }, { "attributes": { "country": <str>, "email": <str>, "emailVerified": <bool>, "firstName": <str>, "username": <str> }, "id": <str>, "type": "users" } ], "links": { "self": <str> } }
- get_album_cover_art(album_id: int | str, /, country_code: str | None = None, *, include_metadata: bool = False, cursor: str | None = None, share_code: str | None = None) dict[str, Any][source]¶
Albums > Get Cover Art Relationship: Get TIDAL catalog information for the cover art of 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.
Example:
"US".- include_metadatabool; keyword-only; default:
False Whether to include metadata for the album cover art.
- cursorstr; keyword-only; optional
Cursor for fetching the next page of results.
Example:
"3nI1Esi".- share_codestr; keyword-only; optional
Share code that grants access to unlisted resources.
- Returns:
- cover_artdict[str, Any]
Page of TIDAL metadata for the album cover art.
Sample response
{ "data": [ { "id": <str>, "type": "artworks" } ], "included": [ { "attributes": { "files": [ { "href": <str>, "meta": { "height": <int>, "width": <int> } } ], "mediaType": "IMAGE" }, "id": <str>, "relationships": { "owners": { "links": { "self": <str> } } }, "type": "artworks" } ], "links": { "meta": { "nextCursor": <str> }, "next": <str>, "self": <str> } }
- get_album_items(album_id: int | str, /, country_code: str | None = None, *, include_metadata: bool = False, cursor: str | None = None, share_code: str | None = None) dict[str, Any][source]¶
Albums > Get Items Relationship: Get TIDAL catalog information for tracks and videos on 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.
Example:
"US".- include_metadatabool; keyword-only; default:
False Whether to include metadata for the album’s tracks and videos.
- cursorstr; keyword-only; optional
Cursor for fetching the next page of results.
Example:
"3nI1Esi".- share_codestr; keyword-only; optional
Share code that grants access to unlisted resources.
- Returns:
- itemsdict[str, Any]
Page of TIDAL metadata for the album’s tracks and videos.
Sample response
{ "data": [ { "id": <str>, "meta": { "trackNumber": <int>, "volumeNumber": <int> }, "type": "tracks" }, { "id": <str>, "meta": { "trackNumber": <int>, "volumeNumber": <int> }, "type": "videos" } ], "included": [ { "attributes": { "accessType": <str>, "availability": <list[str]>, "bpm": <float>, "copyright": { "text": <str> }, "duration": <str>, "explicit": <bool>, "externalLinks": [ { "href": <str>, "meta": { "type": <str> } } ], "isrc": <str>, "key": <str>, "keyScale": <str>, "mediaTags": <list[str]>, "popularity": <float>, "spotlighted": <bool>, "title": <str>, "toneTags": <list[str]>, "version": <str> }, "id": <str>, "relationships": { "albums": { "links": { "self": <str> } }, "artists": { "links": { "self": <str> } }, "genres": { "links": { "self": <str> } }, "lyrics": { "links": { "self": <str> } }, "owners": { "links": { "self": <str> } }, "providers": { "links": { "self": <str> } }, "radio": { "links": { "self": <str> } }, "shares": { "links": { "self": <str> } }, "similarTracks": { "links": { "self": <str> } }, "sourceFile": { "links": { "self": <str> } }, "trackStatistics": { "links": { "self": <str> } } }, "type": "tracks" }, { "attributes": { "availability": <list[str]>, "copyright": { "text": <str> }, "duration": <str>, "explicit": <bool>, "externalLinks": [ { "href": <str>, "meta": { "type": <str> } } ], "isrc": <str>, "popularity": <float>, "releaseDate": <str>, "title": <str> }, "id": <str>, "relationships": { "albums": { "links": { "self": <str> } }, "artists": { "links": { "self": <str> } }, "providers": { "links": { "self": <str> } }, "thumbnailArt": { "links": { "self": <str> } } }, "type": "videos" } ], "links": { "meta": { "nextCursor": <str> }, "next": <str>, "self": <str> } }
- get_album_owners(album_id: int | str, /, *, include_metadata: bool = False, cursor: str | None = None, share_code: str | None = None) dict[str, Any][source]¶
Albums > Get Owners Relationship: Get TIDAL profile information for owners of an album resource.
User authentication
- User authentication
Access information for a resource’s owners.
- Parameters:
- album_idint or str; positional-only
TIDAL ID of the album.
Examples:
46369321,"251380836".- include_metadatabool; keyword-only; default:
False Whether to include metadata for the owners.
- cursorstr; keyword-only; optional
Cursor for fetching the next page of results.
Example:
"3nI1Esi".- share_codestr; keyword-only; optional
Share code that grants access to unlisted resources.
- Returns:
- ownersdict[str, Any]
Page of TIDAL profile information for the album resource’s owners.
Sample response
{ "data": [], "included": [], "links": { "meta": { "nextCursor": <str> }, "next": <str>, "self": <str> } }
- get_album_providers(album_id: int | str, /, country_code: str | None = None, *, include_metadata: bool = False, cursor: str | None = None, share_code: str | None = None) dict[str, Any][source]¶
Albums > Get Providers Relationship: Get TIDAL catalog information for the providers of 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.
Example:
"US".- include_metadatabool; keyword-only; default:
False Whether to include metadata for the album’s providers.
- cursorstr; keyword-only; optional
Cursor for fetching the next page of results.
Example:
"3nI1Esi".- share_codestr; keyword-only; optional
Share code that grants access to unlisted resources.
- Returns:
- providersdict[str, Any]
Page of TIDAL metadata for the album’s providers.
Sample response
{ "data": [ { "id": <str>, "type": <str> } ], "included": [ { "attributes": { "name": <str> }, "id": <str>, "type": <str> } ], "links": { "meta": { "nextCursor": <str> }, "next": <str>, "self": <str> } }
- get_album_usage_rules(album_id: int | str, /, country_code: str | None = None, *, include_metadata: bool = False, share_code: str | None = None) dict[str, Any][source]¶
Albums > Get Usage Rules Relationship: Get TIDAL catalog information for the usage rules 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.
Example:
"US".- include_metadatabool; keyword-only; default:
False Whether to include metadata for the album’s usage rules.
- share_codestr; keyword-only; optional
Share code that grants access to unlisted resources.
- Returns:
- cover_artdict[str, Any]
TIDAL metadata for the album’s usage rules.
Sample response
{ "data": [], "included": [], "links": { "meta": { "nextCursor": <str> }, "next": <str>, "self": <str> } }
- get_albums(album_ids: int | str | Collection[int | str] | None = None, /, *, barcodes: int | str | Collection[int | str] | None = None, owner_ids: int | str | Collection[int | str] | None = None, country_code: str | None = None, expand: str | Collection[str] | None = None, cursor: str | None = None, sort_by: str | None = None, share_code: str | None = None) dict[str, Any][source]¶
Albums > Get Single Album: Get TIDAL catalog information for an album․ Albums > Get Multiple Albums: Get TIDAL catalog information for multiple albums.
User authentication
- User authentication
Access information for a resource’s owners.
Important
Exactly one of album_ids, barcodes, or owner_ids must be provided. When barcodes or owner_ids is specified, the request will always be sent to the endpoint for multiple albums.
- Parameters:
- album_idsint, str, or Collection[int | str]; positional-only; optional
TIDAL IDs of the albums.
Examples:
46369321,"251380836",[46369321, "251380836"].- barcodesint, str, or Collection[int | str]; keyword-only; optional
Barcodes (UPCs and/or EANs) of the albums.
Examples:
602448438034,"075678671173",[602448438034, "075678671173"]- owner_idsint, str, or Collection[int | str]; keyword-only; optional
TIDAL IDs of the album resources’ owners. If authenticated,
"me"can be used in lieu of a TIDAL ID for the current user.Examples: :code:”me”, :code:`123456,
"654321",[123456, "654321"].- country_codestr; keyword-only; optional
ISO 3166-1 alpha-2 country code.
Example:
"US".- expandstr or Collection[str]; keyword-only; optional
Related resources to include metadata for in the response.
Valid values:
"albumStatistics","artists","coverArt","genres","items","owners","priceConfig","providers","replacement","shares","similarAlbums","suggestedCoverArts","usageRules".Examples:
"coverArt",["artists", "items"].- cursorstr; keyword-only; optional
Cursor for fetching the next page of results when retrieving multiple albums.
Example:
"3nI1Esi".- sort_bystr; keyword-only; optional
Field to sort the albums by.
Valid values:
"createdAt","title".- share_codestr; keyword-only; optional
Share code that grants access to unlisted resources.
- Returns:
- albumsdict[str, Any]
TIDAL metadata for the albums.
Sample responses
{ "data": { "attributes": { "accessType": <str>, "availability": <list[str]>, "barcodeId": <str>, "copyright": { "text": <str> }, "duration": <str>, "explicit": <bool>, "externalLinks": [ { "href": <str>, "meta": { "type": <str> } } ], "mediaTags": <list[str]>, "numberOfItems": <int>, "numberOfVolumes": <int>, "popularity": <float>, "releaseDate": <str>, "title": <str>, "type": "ALBUM" }, "id": <str>, "relationships": { "artists": { "data": [ { "id": <str>, "type": "artists" } ], "links": { "self": <str> } }, "coverArt": { "data": [ { "id": <str>, "type": "artworks" } ], "links": { "self": <str> } }, "genres": { "links": { "self": <str> } }, "items": { "data": [ { "id": <str>, "meta": { "trackNumber": <int>, "volumeNumber": <int> }, "type": "tracks" }, { "id": <str>, "meta": { "trackNumber": <int>, "volumeNumber": <int> }, "type": "videos" } ], "links": { "self": <str> } }, "owners": { "links": { "self": <str> } }, "providers": { "data": [ { "id": <str>, "type": "providers" } ], "links": { "self": <str> } }, "similarAlbums": { "data": [ { "id": <str>, "type": "albums" } ], "links": { "meta": { "nextCursor": <str> }, "next": <str>, "self": <str> } }, "suggestedCoverArts" : { "links": { "self": <str> } } }, "type": "albums" }, "included": [ { "attributes": { "accessType": <str>, "availability": <list[str]>, "barcodeId": <str>, "copyright": { "text": <str> }, "duration": <str>, "explicit": <bool>, "externalLinks": [ { "href": <str>, "meta": { "type": <str> } } ], "mediaTags": <list[str]>, "numberOfItems": <int>, "numberOfVolumes": <int>, "popularity": <float>, "releaseDate": <str>, "title": <str>, "type": "ALBUM" }, "id": <str>, "relationships": { "artists": { "links": { "self": <str> } }, "coverArt": { "links": { "self": <str> } }, "genres": { "links": { "self": <str> } }, "items": { "links": { "self": <str> } }, "owners": { "links": { "self": <str> } }, "providers": { "links": { "self": <str> } }, "similarAlbums": { "links": { "self": <str> } }, "suggestedCoverArts" : { "links": { "self": <str> } } }, "type": "albums" }, { "attributes": { "contributionsEnabled": <bool>, "externalLinks": [ { "href": <str>, "meta": { "type": <str> } } ], "name": <str>, "popularity": <float>, "spotlighted": <bool> }, "id": <str>, "relationships": { "albums": { "links": { "self": <str> } }, "biography": { "links": { "self": <str> } }, "followers": { "links": { "self": <str> } }, "following": { "links": { "self": <str> } }, "owners": { "links": { "self": <str> } }, "profileArt": { "links": { "self": <str> } }, "radio": { "links": { "self": <str> } }, "roles": { "links": { "self": <str> } }, "similarArtists": { "links": { "self": <str> } }, "trackProviders": { "links": { "self": <str> } }, "tracks": { "links": { "self": <str> } }, "videos": { "links": { "self": <str> } } }, "type": "artists" }, { "attributes": { "files": [ { "href": <str>, "meta": { "height": <int>, "width": <int> } } ], "mediaType": "IMAGE" }, "id": <str>, "relationships": { "owners": { "links": { "self": <str> } } }, "type": "artworks" }, { "attributes": { "name": <str> }, "id": <str>, "type": "providers" }, { "attributes": { "accessType": <str>, "availability": <list[str]>, "bpm": <float>, "copyright": { "text": <str> }, "duration": <str>, "explicit": <bool>, "externalLinks": [ { "href": <str>, "meta": { "type": <str> } } ], "isrc": <str>, "key": <str>, "keyScale": <str>, "mediaTags": <list[str]>, "popularity": <float>, "spotlighted": <bool>, "title": <str>, "toneTags": <list[str]>, "version": <str> }, "id": <str>, "relationships": { "albums": { "links": { "self": <str> } }, "artists": { "links": { "self": <str> } }, "genres": { "links": { "self": <str> } }, "lyrics": { "links": { "self": <str> } }, "owners": { "links": { "self": <str> } }, "providers": { "links": { "self": <str> } }, "radio": { "links": { "self": <str> } }, "shares": { "links": { "self": <str> } }, "similarTracks": { "links": { "self": <str> } }, "sourceFile": { "links": { "self": <str> } }, "trackStatistics": { "links": { "self": <str> } } }, "type": "tracks" }, { "attributes": { "availability": <list[str]>, "copyright": { "text": <str> }, "duration": <str>, "explicit": <bool>, "externalLinks": [ { "href": <str>, "meta": { "type": <str> } } ], "isrc": <str>, "popularity": <float>, "releaseDate": <str>, "title": <str> }, "id": <str>, "relationships": { "albums": { "links": { "self": <str> } }, "artists": { "links": { "self": <str> } }, "providers": { "links": { "self": <str> } }, "thumbnailArt": { "links": { "self": <str> } } }, "type": "videos" } ], "links": { "meta": { "nextCursor": <str> }, "next": <str>, "self": <str> } }
{ "data": [ { "attributes": { "accessType": <str>, "availability": <list[str]>, "barcodeId": <str>, "copyright": { "text": <str> }, "duration": <str>, "explicit": <bool>, "externalLinks": [ { "href": <str>, "meta": { "type": <str> } } ], "mediaTags": <list[str]>, "numberOfItems": <int>, "numberOfVolumes": <int>, "popularity": <float>, "releaseDate": <str>, "title": <str>, "type": "ALBUM" }, "id": <str>, "relationships": { "artists": { "data": [ { "id": <str>, "type": "artists" } ], "links": { "self": <str> } }, "coverArt": { "data": [ { "id": <str>, "type": "artworks" } ], "links": { "self": <str> } }, "genres": { "links": { "self": <str> } }, "items": { "data": [ { "id": <str>, "meta": { "trackNumber": <int>, "volumeNumber": <int> }, "type": "tracks" }, { "id": <str>, "meta": { "trackNumber": <int>, "volumeNumber": <int> }, "type": "videos" } ], "links": { "self": <str> } }, "owners": { "links": { "self": <str> } }, "providers": { "data": [ { "id": <str>, "type": "providers" } ], "links": { "self": <str> } }, "similarAlbums": { "data": [ { "id": <str>, "type": "albums" } ], "links": { "meta": { "nextCursor": <str> }, "next": <str>, "self": <str> } }, "suggestedCoverArts" : { "links": { "self": <str> } } }, "type": "albums" } ], "included": [ { "attributes": { "accessType": <str>, "availability": <list[str]>, "barcodeId": <str>, "copyright": { "text": <str> }, "duration": <str>, "explicit": <bool>, "externalLinks": [ { "href": <str>, "meta": { "type": <str> } } ], "mediaTags": <list[str]>, "numberOfItems": <int>, "numberOfVolumes": <int>, "popularity": <float>, "releaseDate": <str>, "title": <str>, "type": "ALBUM" }, "id": <str>, "relationships": { "artists": { "links": { "self": <str> } }, "coverArt": { "links": { "self": <str> } }, "genres": { "links": { "self": <str> } }, "items": { "links": { "self": <str> } }, "owners": { "links": { "self": <str> } }, "providers": { "links": { "self": <str> } }, "similarAlbums": { "links": { "self": <str> } }, "suggestedCoverArts" : { "links": { "self": <str> } } }, "type": "albums" }, { "attributes": { "contributionsEnabled": <bool>, "externalLinks": [ { "href": <str>, "meta": { "type": <str> } } ], "name": <str>, "popularity": <float>, "spotlighted": <bool> }, "id": <str>, "relationships": { "albums": { "links": { "self": <str> } }, "biography": { "links": { "self": <str> } }, "followers": { "links": { "self": <str> } }, "following": { "links": { "self": <str> } }, "owners": { "links": { "self": <str> } }, "profileArt": { "links": { "self": <str> } }, "radio": { "links": { "self": <str> } }, "roles": { "links": { "self": <str> } }, "similarArtists": { "links": { "self": <str> } }, "trackProviders": { "links": { "self": <str> } }, "tracks": { "links": { "self": <str> } }, "videos": { "links": { "self": <str> } } }, "type": "artists" }, { "attributes": { "files": [ { "href": <str>, "meta": { "height": <int>, "width": <int> } } ], "mediaType": "IMAGE" }, "id": <str>, "relationships": { "owners": { "links": { "self": <str> } } }, "type": "artworks" }, { "attributes": { "name": <str> }, "id": <str>, "type": "providers" }, { "attributes": { "accessType": <str>, "availability": <list[str]>, "bpm": <float>, "copyright": { "text": <str> }, "duration": <str>, "explicit": <bool>, "externalLinks": [ { "href": <str>, "meta": { "type": <str> } } ], "isrc": <str>, "key": <str>, "keyScale": <str>, "mediaTags": <list[str]>, "popularity": <float>, "spotlighted": <bool>, "title": <str>, "toneTags": <list[str]>, "version": <str> }, "id": <str>, "relationships": { "albums": { "links": { "self": <str> } }, "artists": { "links": { "self": <str> } }, "genres": { "links": { "self": <str> } }, "lyrics": { "links": { "self": <str> } }, "owners": { "links": { "self": <str> } }, "providers": { "links": { "self": <str> } }, "radio": { "links": { "self": <str> } }, "shares": { "links": { "self": <str> } }, "similarTracks": { "links": { "self": <str> } }, "sourceFile": { "links": { "self": <str> } }, "trackStatistics": { "links": { "self": <str> } } }, "type": "tracks" }, { "attributes": { "availability": <list[str]>, "copyright": { "text": <str> }, "duration": <str>, "explicit": <bool>, "externalLinks": [ { "href": <str>, "meta": { "type": <str> } } ], "isrc": <str>, "popularity": <float>, "releaseDate": <str>, "title": <str> }, "id": <str>, "relationships": { "albums": { "links": { "self": <str> } }, "artists": { "links": { "self": <str> } }, "providers": { "links": { "self": <str> } }, "thumbnailArt": { "links": { "self": <str> } } }, "type": "videos" } ], "links": { "meta": { "nextCursor": <str> }, "next": <str>, "self": <str> } }
- get_similar_albums(album_id: int | str, /, country_code: str | None = None, *, include_metadata: bool = False, cursor: str | None = None, share_code: str | None = None) dict[str, Any][source]¶
Albums > Get Similar Albums Relationship: 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.
Example:
"US".- include_metadatabool; keyword-only; default:
False Whether to include metadata for the similar albums.
- cursorstr; keyword-only; optional
Cursor for fetching the next page of results.
Example:
"3nI1Esi".- share_codestr; keyword-only; optional
Share code that grants access to unlisted resources.
- Returns:
- albumsdict[str, Any]
Page of TIDAL metadata for the similar albums.
Sample response
{ "data": [ { "id": <str>, "type": "albums" } ], "included": [ { "attributes": { "accessType": <str>, "availability": <list[str]>, "barcodeId": <str>, "copyright": { "text": <str> }, "duration": <str>, "explicit": <bool>, "externalLinks": [ { "href": <str>, "meta": { "type": <str> } } ], "mediaTags": <list[str]>, "numberOfItems": <int>, "numberOfVolumes": <int>, "popularity": <float>, "releaseDate": <str>, "title": <str>, "type": "ALBUM" }, "id": <str>, "relationships": { "artists": { "links": { "self": <str> } }, "coverArt": { "links": { "self": <str> } }, "genres": { "links": { "self": <str> } }, "items": { "links": { "self": <str> } }, "owners": { "links": { "self": <str> } }, "providers": { "links": { "self": <str> } }, "similarAlbums": { "links": { "self": <str> } }, "suggestedCoverArts" : { "links": { "self": <str> } } }, "type": "albums" } ], "links": { "meta": { "nextCursor": <str> }, "next": <str>, "self": <str> } }
- get_user_saved_albums(*, collection_id: str | None = None, user_id: int | str | None = None, country_code: str | None = None, locale: str | None = None, include_metadata: bool = False, cursor: str | None = None, sort_by: str | None = None, descending: bool | None = None) dict[str, Any][source]¶
User Collection Albums > Get Items Relationship: Get TIDAL catalog information for albums in a user collection․ User Collections > Get Albums Relationship: Get TIDAL catalog information for albums in a user’s collection.
Authorization scope
collection.readscopeRead access to a user’s collection.
Important
At most one of collection_id or user_id must be provided. If user_id is provided, the legacy
GET /userCollections/{user_id}/relationships/albumsendpoint is used.- Parameters:
- collection_idstr; keyword-only; optional
TIDAL ID of the user collection. If authenticated,
"me"can be used in lieu of a TIDAL ID for the current user’s collection. If not specified,"me"is used.- user_idint or str; keyword-only; optional
TIDAL ID of the user.
- country_codestr; keyword-only; optional
ISO 3166-1 alpha-2 country code.
Example:
"US".- localestr; keyword-only; optional
IETF BCP 47 language tag.
- include_metadatabool; keyword-only; default:
False Whether to include metadata for the albums in the user’s collection.
- cursorstr; keyword-only; optional
Cursor for fetching the next page of results.
Example:
"3nI1Esi".- sort_bystr; keyword-only; optional
Field to sort the albums by.
Valid values:
"addedAt","artists.name,"releaseDate","title".- 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
{ "data": [ { "id": <str>, "meta": { "addedAt": <str> }, "type": "albums" } ], "included": [ { "attributes": { "accessType": <str>, "availability": <list[str]>, "barcodeId": <str>, "copyright": { "text": <str> }, "duration": <str>, "explicit": <bool>, "externalLinks": [ { "href": <str>, "meta": { "type": <str> } } ], "mediaTags": <list[str]>, "numberOfItems": <int>, "numberOfVolumes": <int>, "popularity": <float>, "releaseDate": <str>, "title": <str>, "type": "ALBUM" }, "id": <str>, "relationships": { "artists": { "links": { "self": <str> } }, "coverArt": { "links": { "self": <str> } }, "genres": { "links": { "self": <str> } }, "items": { "links": { "self": <str> } }, "owners": { "links": { "self": <str> } }, "providers": { "links": { "self": <str> } }, "similarAlbums": { "links": { "self": <str> } }, "suggestedCoverArts" : { "links": { "self": <str> } } }, "type": "albums" } ], "links": { "meta": { "nextCursor": <str> }, "next": <str>, "self": <str> } }
- remove_saved_albums(album_ids: int | str | dict[str, int | str] | Collection[int | str | dict[str, int | str]], /, *, collection_id: str | None = None, user_id: int | str | None = None, country_code: str | None = None) None[source]¶
User Collection Albums > Delete from Items Relationship: Remove albums from a user collection․ User Collections > Delete from Albums Relationship: Remove albums from a user’s collection.
Authorization scope
collection.writescopeWrite access to a user’s collection.
Important
At most one of collection_id or user_id must be provided. If user_id is provided, the legacy
DELETE /userCollections/{user_id}/relationships /albumsendpoint is used.- Parameters:
- album_idsint, str, dict[str, int | str], or Collection[int | str | dict[str, int | str]]; positional-only
TIDAL IDs and/or resource identifiers of the albums.
Examples:
46369321"251380836"{"id": "46369321", "types": "albums"}["251380836", {"id": "46369321", "types": "albums"}]
- collection_idstr; keyword-only; optional
TIDAL ID of the user collection. If authenticated,
"me"can be used in lieu of a TIDAL ID for the current user’s collection. If not specified,"me"is used.- user_idint or str; keyword-only; optional
TIDAL ID of the user.
- save_albums(album_ids: int | str | dict[str, int | str] | Collection[int | str | dict[str, int | str]], /, *, collection_id: str | None = None, user_id: int | str | None = None, country_code: str | None = None) None[source]¶
User Collection Albums > Add to Items Relationship: Add albums to a user collection․ User Collections > Add to Albums Relationship: Add albums to a user’s collection.
Authorization scope
collection.writescopeWrite access to a user’s collection.
Important
At most one of collection_id or user_id must be provided. If user_id is provided, the legacy
POST /userCollections/{user_id}/relationships/albumsendpoint is used.- Parameters:
- album_idsint, str, dict[str, int | str], or Collection[int | str | dict[str, int | str]]; positional-only
TIDAL IDs and/or resource identifiers of the albums.
Examples:
46369321"251380836"{"id": "46369321", "types": "albums"}["251380836", {"id": "46369321", "types": "albums"}]
- collection_idstr; keyword-only; optional
TIDAL ID of the user collection. If authenticated,
"me"can be used in lieu of a TIDAL ID for the current user’s collection. If not specified,"me"is used.- user_idint or str; keyword-only; optional
TIDAL ID of the user.
- country_codestr; keyword-only; optional
ISO 3166-1 alpha-2 country code.
Example:
"US".
- search_albums(query: str, /, country_code: str | None = None, *, include_explicit: bool | None = None, include_metadata: bool = False, cursor: str | None = None) dict[str, Any][source]¶
Search Results > Get Albums Relationship: Search for albums in the TIDAL catalog.
Authorization scope
search.readscopeRead personalized search results.
- Parameters:
- querystr; positional-only
Search query.
- country_codestr; optional
ISO 3166-1 alpha-2 country code.
Example:
"US".- include_explicitbool; keyword-only; optional
Whether to include explicit content in the results.
API default:
True.- include_metadatabool; keyword-only; default:
False Whether to include metadata for the matching albums.
- cursorstr; keyword-only; optional
Cursor for fetching the next page of results.
Example:
"3nI1Esi".
- Returns:
- albumsdict[str, Any]
Page of TIDAL metadata for the matching albums.
Sample response
{ "data": [ { "id": <str>, "type": "albums" } ], "included": [ { "attributes": { "accessType": <str>, "availability": <list[str]>, "barcodeId": <str>, "copyright": { "text": <str> }, "duration": <str>, "explicit": <bool>, "externalLinks": [ { "href": <str>, "meta": { "type": <str> } } ], "mediaTags": <list[str]>, "numberOfItems": <int>, "numberOfVolumes": <int>, "popularity": <float>, "releaseDate": <str>, "title": <str>, "type": "ALBUM" }, "id": <str>, "relationships": { "artists": { "links": { "self": <str> } }, "coverArt": { "links": { "self": <str> } }, "genres": { "links": { "self": <str> } }, "items": { "links": { "self": <str> } }, "owners": { "links": { "self": <str> } }, "providers": { "links": { "self": <str> } }, "similarAlbums": { "links": { "self": <str> } }, "suggestedCoverArts" : { "links": { "self": <str> } } }, "type": "albums" } ], "links": { "meta": { "nextCursor": <str> }, "next": <str>, "self": <str> } }