ArtistsAPI¶
- class minim.api.tidal.ArtistsAPI(client: APIClient, /)[source]¶
Bases:
TIDALResourceAPIArtist Roles and Artists 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
User Collection Artists > Add to Items Relationship: Add artists to a user collection․ User Collections > Add to Artists Relationship: Add artists to a user's collection.
Artists > Get Albums Relationship: Get TIDAL catalog information for albums by an artist.
Artists > Get Biography Relationship: Get an artist's biography.
User Collection Artists > Get User Artist Collection: Get TIDAL catalog information for a user artist collection.
Artists > Get Radio Relationship: Get TIDAL catalog information for an artist's mix.
Artists > Get Owners Relationship: Get TIDAL profile information for the owners of an artist resource.
Artists > Get Profile Art Relationship: Get TIDAL catalog information for the profile art for an artist.
Artists > Get Roles Relationship: Get TIDAL catalog information for an artist's roles.
Artists > Get Track Providers: Get TIDAL catalog information for the providers of an artist's tracks.
Artists > Get Tracks Relationship: Get TIDAL catalog information for tracks by an artist.
Artists > Get Videos Relationship: Get TIDAL catalog information for videos by an artist.
Artists > Get Single Artist: Get TIDAL catalog information for an artist․ Artists > Get Multiple Artists: Get TIDAL catalog information for multiple artists.
Artist Roles > Get Single Artist Role: Get TIDAL catalog information for an artist role․ Artist Roles > Get Multiple Artist Roles: Get TIDAL catalog information for multiple artist roles.
Artists > Get Similar Artists Relationship: Get TIDAL catalog information for similar artists
User Collection Artists > Get Items Relationship: Get TIDAL catalog information for artists in a user collection․ User Collections > Get Artists Relationship: Get TIDAL catalog information for artists in a user's collection.
Search Results > Get Artists Relationship: Search for artists in the TIDAL catalog.
User Collection Artists > Delete from Items Relationship: Remove artists from a user collection․ User Collections > Delete from Items Relationship: Remove artists from a user's collection.
- follow_artists(artist_ids: int | str | dict[str, int | str] | list[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 Artists > Add to Items Relationship: Add artists to a user collection․ User Collections > Add to Artists Relationship: Add artists 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/artistsendpoint is used.- Parameters:
- artist_idsint, str, dict[str, int | str], or Collection[int | str | dict[str, int | str]]; positional-only
TIDAL IDs and/or resource identifiers of the artists.
Examples:
1566"4676988"{"id": "1566", "types": "artists"}["4676988", {"id": "46369321", "types": "artists"}]
- 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".
- get_artist_albums(artist_id: int | str, /, country_code: str | None = None, *, include_metadata: bool = False, cursor: str | None = None) dict[str, Any][source]¶
Artists > Get Albums Relationship: Get TIDAL catalog information for albums by an artist.
- Parameters:
- artist_idint or str; positional-only
TIDAL ID of the artist.
Examples:
1566,"4676988".- country_codestr; optional
ISO 3166-1 alpha-2 country code.
Example:
"US".- include_metadatabool; keyword-only; default:
False Whether to include metadata for the artist’s 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 artist’s 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_artist_biography(artist_id: int | str, /, country_code: str | None = None, *, include_metadata: bool = False) dict[str, Any][source]¶
Artists > Get Biography Relationship: Get an artist’s biography.
- Parameters:
- artist_idint or str; positional-only
TIDAL ID of the artist.
Examples:
1566,"4676988".- country_codestr; optional
ISO 3166-1 alpha-2 country code.
Example:
"US".- include_metadatabool; keyword-only; default:
False Whether to include metadata for the artist’s biography.
- Returns:
- biographydict[str, Any]
TIDAL metadata for the artist’s biography.
Sample response
{ "data": { "id": <str>, "type": "artistBiographies" }, "included": [], "links": { "self": <str> } }
- get_artist_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 Artists > Get User Artist Collection: Get TIDAL catalog information for a user artist 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 artist collection.
Sample response
{ "data": { "attributes": {}, "id": <str>, "relationships": { "items": { "data": [ { "id": <str>, "meta": { "addedAt": <str> }, "type": "artists" } ], "links": { "self": <str> } }, "owners": { "data": [ { "id": <str>, "type": "users" } ], "links": { "self": <str> } } }, "type": "userCollectionArtists" }, "included": [ { "attributes": { "externalLinks": [ { "href": <str>, "meta": { "type": <str> } } ], "name": <str>, "popularity": <float> }, "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": { "country": <str>, "email": <str>, "emailVerified": <bool>, "firstName": <str>, "username": <str> }, "id": <str>, "type": "users" } ], "links": { "self": <str> } }
- get_artist_mix(artist_id: int | str, /, country_code: str | None = None, *, include_metadata: bool = False, cursor: str | None = None) dict[str, Any][source]¶
Artists > Get Radio Relationship: Get TIDAL catalog information for an artist’s mix.
- Parameters:
- artist_idint or str; positional-only
TIDAL ID of the artist.
Examples:
1566,"4676988".- country_codestr; optional
ISO 3166-1 alpha-2 country code.
Example:
"US".- include_metadatabool; keyword-only; default:
False Whether to include metadata for the artist’s mix.
- cursorstr; keyword-only; optional
Cursor for fetching the next page of results.
Example:
"3nI1Esi".
- Returns:
- mixdict[str, Any]
Page of TIDAL metadata for the artist’s mix.
Sample response
{ "data": [ { "id": <str>, "type": "playlists" } ], "included": [ { "attributes": { "accessType": <str>, "bounded": <bool>, "createdAt": <str>, "description": "Artist Radio", "externalLinks": [ { "href": <str>, "meta": { "type": <str> } } ], "lastModifiedAt": <str>, "name": <str>, "playlistType": "MIX" }, "id": <str>, "relationships": { "coverArt": { "links": { "self": <str> } }, "items": { "links": { "self": <str> } }, "owners": { "links": { "self": <str> } } }, "type": "playlists" } ], "links": { "meta": { "nextCursor": <str> }, "next": <str>, "self": <str> } }
- get_artist_owners(artist_id: int | str, /, *, include_metadata: bool = False, cursor: str | None = None) dict[str, Any][source]¶
Artists > Get Owners Relationship: Get TIDAL profile information for the owners of an artist resource.
User authentication
- User authentication
Access information for a resource’s owners.
- Parameters:
- artist_idint or str; positional-only
TIDAL ID of the artist.
Examples:
1566,"4676988".- 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".
- Returns:
- ownersdict[str, Any]
Page of TIDAL profile information for the artist resource’s owners.
Sample response
{ "data": [], "included": [], "links": { "meta": { "nextCursor": <str> }, "next": <str>, "self": <str> } }
- get_artist_profile_art(artist_id: int | str, /, country_code: str | None = None, *, include_metadata: bool = False, cursor: str | None = None) dict[str, Any][source]¶
Artists > Get Profile Art Relationship: Get TIDAL catalog information for the profile art for an artist.
- Parameters:
- artist_idint or str; positional-only
TIDAL ID of the artist.
Examples:
1566,"4676988".- country_codestr; optional
ISO 3166-1 alpha-2 country code. Example:
"US".- include_metadatabool; keyword-only; default:
False Whether to include metadata for the artist’s profile art.
- cursorstr; keyword-only; optional
Cursor for fetching the next page of results.
Example:
"3nI1Esi".
- Returns:
- profile_artdict[str, Any]
Page of TIDAL metadata for the artist’s profile 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_artist_roles(artist_id: int | str, /, *, include_metadata: bool = False, cursor: str | None = None) dict[str, Any][source]¶
Artists > Get Roles Relationship: Get TIDAL catalog information for an artist’s roles.
- Parameters:
- artist_idint or str; positional-only
TIDAL ID of the artist.
Examples:
1566,"4676988".- include_metadatabool; keyword-only; default:
False Whether to include metadata for the artist’s roles.
- cursorstr; keyword-only; optional
Cursor for fetching the next page of results.
Example:
"3nI1Esi".
- Returns:
- rolesdict[str, Any]
Page of TIDAL metadata for the artist’s roles.
Sample response
{ "data": [ { "id": <str>, "type": "artistRoles" } ], "included": [ { "attributes": { "name": <str> }, "id": <str>, "type": "artistRoles" } ], "links": { "meta": { "nextCursor": <str> }, "next": <str>, "self": <str> } }
- get_artist_track_providers(artist_id: int | str, /, *, include_metadata: bool = False, cursor: str | None = None) dict[str, Any][source]¶
Artists > Get Track Providers: Get TIDAL catalog information for the providers of an artist’s tracks.
- Parameters:
- artist_idint or str; positional-only
TIDAL ID of the artist.
Examples:
1566,"4676988".- country_codestr; optional
ISO 3166-1 alpha-2 country code.
Example:
"US".- include_metadatabool; keyword-only; default:
False Whether to include metadata for the artist’s track providers.
- cursorstr; keyword-only; optional
Cursor for fetching the next page of results.
Example:
"3nI1Esi".
- Returns:
- providersdict[str, Any]
Page of TIDAL metadata for the artist’s track providers.
Sample response
{ "data": [ { "id": <str>, "meta": { "numberOfTracks": <int> }, "type": "providers" } ], "included": [ { "attributes": { "name": <str> }, "id": <str>, "type": "providers" } ], "links": { "meta": { "nextCursor": <str> }, "next": <str>, "self": <str> } }
- get_artist_tracks(artist_id: int | str, /, country_code: str | None = None, *, group_by: str = 'FINGERPRINT', include_metadata: bool = False, cursor: str | None = None) dict[str, Any][source]¶
Artists > Get Tracks Relationship: Get TIDAL catalog information for tracks by an artist.
- Parameters:
- artist_idint or str; positional-only
TIDAL ID of the artist.
Examples:
1566,"4676988".- country_codestr; optional
ISO 3166-1 alpha-2 country code.
Example:
"US".- group_bystr; keyword-only; default:
"FINGERPRINT" How the returned tracks are grouped.
Valid values:
"FINGERPRINT"– Collapses tracks that share the same audio fingerprint."ID"– Returns every track as a separate item.
- include_metadatabool; keyword-only; default:
False Whether to include metadata for the artist’s tracks.
- cursorstr; keyword-only; optional
Cursor for fetching the next page of results.
Example:
"3nI1Esi".
- Returns:
- tracksdict[str, Any]
Page of TIDAL metadata for the artist’s tracks.
Sample response
{ "data": [ { "id": <str>, "type": "tracks" } ], "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" } ], "links": { "meta": { "nextCursor": <str> }, "next": <str>, "self": <str> } }
- get_artist_videos(artist_id: int | str, /, country_code: str | None = None, *, include_metadata: bool = False, cursor: str | None = None) dict[str, Any][source]¶
Artists > Get Videos Relationship: Get TIDAL catalog information for videos by an artist.
- Parameters:
- artist_idint or str; positional-only
TIDAL ID of the artist.
Examples:
1566,"4676988".- country_codestr; optional
ISO 3166-1 alpha-2 country code.
Example:
"US".- include_metadatabool; keyword-only; default:
False Whether to include metadata for the artist’s videos.
- cursorstr; keyword-only; optional
Cursor for fetching the next page of results.
Example:
"3nI1Esi".
- Returns:
- videosdict[str, Any]
Page of TIDAL metadata for the artist’s videos.
Sample response
{ "data": [ { "id": <str>, "type": "videos" } ], "included": [ { "attributes": { "copyright": { "text": <str> }, "duration": <str>, "explicit": false, "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_artists(artist_ids: int | str | Collection[int | str] | None = None, /, *, handles: str | Collection[str] | None = None, owner_ids: int | str | Collection[int | str] | None = None, country_code: str | None = None, expand: str | Collection[str] | None = None) dict[str, Any][source]¶
Artists > Get Single Artist: Get TIDAL catalog information for an artist․ Artists > Get Multiple Artists: Get TIDAL catalog information for multiple artists.
User authentication
- User authentication
Access information for a resource’s owners.
Important
Exactly one of artist_ids, handles, or owner_ids must be provided. When handles or owner_ids is specified, the request will always be sent to the endpoint for multiple artists.
- Parameters:
- artist_idsint, str, or Collection[int | str]; positional-only; optional
TIDAL IDs of the artists.
Examples:
1566,"4676988",[1566, "4676988"].- handlesstr or Collection[str]; keyword-only; optional
Artist handles.
Example:
"jayz".- owner_idsint, str, or Collection[int | str]; keyword-only; optional
TIDAL IDs of the artist 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:
"albums","biography","followers","following","owners","profileArt","radio","roles","similarArtists","trackProviders","tracks","videos".Examples:
"profileArt",["albums", "tracks"].
- Returns:
- artistsdict[str, Any]
TIDAL metadata for the artists.
Sample responses
{ "data": { "attributes": { "contributionsEnabled": <bool>, "externalLinks": [ { "href": <str>, "meta": { "type": <str> } } ], "name": <str>, "popularity": <float>, "spotlighted": <bool> }, "id": <str>, "relationships": { "albums": { "data": [ { "id": <str>, "type": "albums" } ], "links": { "meta": { "nextCursor": <str> }, "next": <str>, "self": <str> } }, "biography": { "data": { "id": <str>, "type": "artistBiographies" }, "links": { "self": <str> } }, "followers": { "data": [], "links": { "self": <str> } }, "following": { "data": [], "links": { "self": <str> } }, "owners": { "data": [], "links": { "self": <str> } }, "profileArt": { "data": [ { "id": <str>, "type": "artworks" } ], "links": { "self": <str> } }, "radio": { "data": [ { "id": <str>, "type": "playlists" } ], "links": { "self": <str> } }, "roles": { "data": [ { "id": <str>, "type": "artistRoles" } ], "links": { "self": <str> } }, "similarArtists": { "links": { "self": <str> } }, "trackProviders": { "links": { "self": <str> } }, "tracks": { "links": { "self": <str> } }, "videos": { "links": { "self": <str> } } }, "type": "artists" }, "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": { "name": <str> }, "id": <str>, "type": "artistRoles" }, { "attributes": { "files": [ { "href": <str>, "meta": { "height": <int>, "width": <int> } } ], "mediaType": "IMAGE" }, "id": <str>, "relationships": { "owners": { "links": { "self": <str> } } }, "type": "artworks" }, { "attributes": { "accessType": <str>, "bounded": <bool>, "createdAt": <str>, "description": "Artist Radio", "externalLinks": [ { "href": <str>, "meta": { "type": <str> } } ], "lastModifiedAt": <str>, "name": <str>, "playlistType": "MIX" }, "id": <str>, "relationships": { "coverArt": { "links": { "self": <str> } }, "items": { "links": { "self": <str> } }, "owners": { "links": { "self": <str> } } }, "type": "playlists" }, { "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": { "name": <str> }, "id": <str>, "type": "providers" }, { "attributes": { "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": { "self": <str> } }
{ "data": [ { "attributes": { "contributionsEnabled": <bool>, "externalLinks": [ { "href": <str>, "meta": { "type": <str> } } ], "name": <str>, "popularity": <float>, "spotlighted": <bool> }, "id": <str>, "relationships": { "albums": { "data": [ { "id": <str>, "type": "albums" } ], "links": { "meta": { "nextCursor": <str> }, "next": <str>, "self": <str> } }, "biography": { "data": { "id": <str>, "type": "artistBiographies" }, "links": { "self": <str> } }, "followers": { "data": [], "links": { "self": <str> } }, "following": { "data": [], "links": { "self": <str> } }, "owners": { "data": [], "links": { "self": <str> } }, "profileArt": { "data": [ { "id": <str>, "type": "artworks" } ], "links": { "self": <str> } }, "radio": { "data": [ { "id": <str>, "type": "playlists" } ], "links": { "self": <str> } }, "roles": { "data": [ { "id": <str>, "type": "artistRoles" } ], "links": { "self": <str> } }, "similarArtists": { "links": { "self": <str> } }, "trackProviders": { "links": { "self": <str> } }, "tracks": { "links": { "self": <str> } }, "videos": { "links": { "self": <str> } } }, "type": "artists" } ], "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": { "name": <str> }, "id": <str>, "type": "artistRoles" }, { "attributes": { "files": [ { "href": <str>, "meta": { "height": <int>, "width": <int> } } ], "mediaType": "IMAGE" }, "id": <str>, "relationships": { "owners": { "links": { "self": <str> } } }, "type": "artworks" }, { "attributes": { "accessType": <str>, "bounded": <bool>, "createdAt": <str>, "description": "Artist Radio", "externalLinks": [ { "href": <str>, "meta": { "type": <str> } } ], "lastModifiedAt": <str>, "name": <str>, "playlistType": "MIX" }, "id": <str>, "relationships": { "coverArt": { "links": { "self": <str> } }, "items": { "links": { "self": <str> } }, "owners": { "links": { "self": <str> } } }, "type": "playlists" }, { "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": { "name": <str> }, "id": <str>, "type": "providers" }, { "attributes": { "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": { "self": <str> } }
- get_roles(artist_role_ids: int | str | Collection[int | str], /) dict[str, Any][source]¶
Artist Roles > Get Single Artist Role: Get TIDAL catalog information for an artist role․ Artist Roles > Get Multiple Artist Roles: Get TIDAL catalog information for multiple artist roles.
- Parameters:
- artist_role_idsint, str, or Collection[int | str]; positional-only
TIDAL IDs of the artist roles.
Examples:
1,"2",[3, "4"].
- Returns:
- artist_rolesdict[str, Any]
TIDAL catalog information for the artist roles.
Sample responses
{ "data": { "attributes": { "name": <str> }, "id": <str>, "type": "artistRoles" }, "links": { "self": <str> } }
{ "data": [ { "attributes": { "name": <str> }, "id": <str>, "type": "artistRoles" } ], "links": { "self": <str> } }
- get_similar_artists(artist_id: int | str, /, country_code: str | None = None, *, include_metadata: bool = False, cursor: str | None = None) dict[str, Any][source]¶
Artists > Get Similar Artists Relationship: Get TIDAL catalog information for similar artists
- Parameters:
- artist_idint or str; positional-only
TIDAL ID of the artist.
Examples:
1566,"4676988".- 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 artists.
- cursorstr; keyword-only; optional
Cursor for fetching the next page of results.
Example:
"3nI1Esi".
- Returns:
- artistsdict[str, Any]
Page of TIDAL metadata for the similar 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_user_followed_artists(*, 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 Artists > Get Items Relationship: Get TIDAL catalog information for artists in a user collection․ User Collections > Get Artists Relationship: Get TIDAL catalog information for artists 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/artistsendpoint 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 artists 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 artists by.
Valid values:
"addedAt","name".- descendingbool; keyword-only; optional
Whether to sort in descending order.
API default:
False.
- Returns:
- artistsdict[str, Any]
Page of TIDAL metadata for the artists in the user’s collection.
Sample response
{ "data": [ { "id": <str>, "meta": { "addedAt": <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> } }
- search_artists(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 Artists Relationship: Search for artists 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 items with explicit language.
API default:
True.- include_metadatabool; keyword-only; default:
False Whether to include metadata for the matching artists.
- cursorstr; keyword-only; optional
Cursor for fetching the next page of results.
Example:
"3nI1Esi".
- Returns:
- artistsdict[str, Any]
Page of TIDAL metadata for the matching 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> } }
- unfollow_artists(artist_ids: int | str | dict[str, int | str] | list[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 Artists > Delete from Items Relationship: Remove artists from a user collection․ User Collections > Delete from Items Relationship: Remove artists 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 /artistsendpoint is used.- Parameters:
- artist_idsint, str, dict[str, int | str], or Collection[int | str | dict[str, int | str]]; positional-only
TIDAL IDs and/or resource identifiers of the artists.
Examples:
1566"4676988"{"id": "1566", "types": "artists"}["4676988", {"id": "46369321", "types": "artists"}]
- 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.