PrivateSearchAPI

class minim.api.tidal.PrivateSearchAPI(client: APIClient, /)

Bases: PrivateTIDALResourceAPI

Search 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

search	Search for albums, artists, playlists, tracks, and videos in the TIDAL catalog.
search_albums	Search for albums in the TIDAL catalog.
search_artists	Search for artists in the TIDAL catalog.
search_playlists	Search for playlists in the TIDAL catalog.
search_tracks	Search for tracks in the TIDAL catalog.
search_videos	Search for videos in the TIDAL catalog.

search(query: str, /, country_code: str | None = None, *, limit: int | None = None, offset: int | None = None) → dict[str, Any]

Search for albums, artists, playlists, tracks, and videos in the TIDAL catalog.

Parameters:

querystr; positional-only

Search query.

country_codestr; keyword-only; 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 for each resource type.

Valid range: 1 to 100.

API default: 10.

offsetint; keyword-only; optional

Index of the first item to return for each resource type. 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 matching items.

Sample response

{
  "albums": {
    "items": [
      {
        "adSupportedStreamReady": <bool>,
        "allowStreaming": <bool>,
        "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>
  },
  "artists": {
    "items": [
      {
        "artistRoles": [
          {
            "category": <str>,
            "categoryId": <int>
          }
        ],
        "artistTypes": <list[str]>
        "handle": <str>,
        "id": <int>,
        "mixes": {
          "ARTIST_MIX": <str>
        },
        "name": <str>,
        "picture": <str>,
        "popularity": <int>,
        "selectedAlbumCoverFallback": None,
        "spotlighted": <bool>,
        "url": <str>,
        "userId": <int>
      }
    ],
    "limit": <int>,
    "offset": <int>,
    "totalNumberOfItems": <int>
  },
  "playlists": {
    "items": [
      {
        "created": <str>,
        "creator": {
          "id": <int>,
          "name": <str>,
          "picture": <str>,
          "selectedAlbumCoverFallback": None,
          "type": <str>
        },
        "customImageUrl": <str>,
        "description": <str>,
        "duration": <int>,
        "image": <str>,
        "lastItemAddedAt": <str>,
        "lastUpdated": <str>,
        "numberOfTracks": <int>,
        "numberOfVideos": <int>,
        "popularity": <int>,
        "promotedArtists": [
          {
            "handle": <str>,
            "id": <int>,
            "name": <str>,
            "picture": <str>,
            "type": "MAIN"
          }
        ],
        "publicPlaylist": <bool>,
        "squareImage": <str>,
        "title": <str>,
        "type": <str>,
        "url": f"http://www.tidal.com/playlist/{uuid}",
        "uuid": <str>
      }
    ],
    "limit": <int>,
    "offset": <int>,
    "totalNumberOfItems": <int>
  },
  "topHit": {
    "type": "ARTISTS",
    "value": {
      "artistRoles": [
        {
          "category": <str>,
          "categoryId": <int>
        }
      ],
      "artistTypes": <list[str]>,
      "handle": <str>,
      "id": <int>,
      "mixes": {
        "ARTIST_MIX": <str>
      },
      "name": <str>,
      "picture": <str>,
      "popularity": <int>,
      "selectedAlbumCoverFallback": None,
      "spotlighted": <bool>,
      "url": <str>,
      "userId": <int>
    }
  },
  "tracks": {
    "items": [
      {
        "accessType": <str>,
        "adSupportedStreamReady": <bool>,
        "album": {
          "cover": <str>,
          "id": <int>,
          "releaseDate": <str>,
          "title": <str>,
          "vibrantColor": <str>,
          "videoCover": <str>
        },
        "allowStreaming": <bool>,
        "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": f"http://www.tidal.com/track/{id}",
        "version": <str>,
        "volumeNumber": <int>
      }
    ],
    "limit": <int>,
    "offset": <int>,
    "totalNumberOfItems": <int>
  },
  "videos": {
    "items": [
      {
        "adSupportedStreamReady": <bool>,
        "adsPrePaywallOnly": <bool>,
        "adsUrl": <str>,
        "album": {
          "cover": <str>,
          "id": <int>,
          "title": <str>,
          "vibrantColor": <str>,
          "videoCover": <str>
        },
        "allowStreaming": <bool>,
        "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": <int>,
        "releaseDate": <str>,
        "stemReady": <bool>,
        "streamReady": <bool>,
        "streamStartDate": <str>,
        "title": <str>,
        "trackNumber": <int>,
        "type": "Music Video",
        "vibrantColor": <str>,
        "volumeNumber": <int>
      }
    ],
    "limit": <int>,
    "offset": <int>,
    "totalNumberOfItems": <int>
  }
}

search_albums(query: str, /, country_code: str | None = None, *, limit: int | None = None, offset: int | None = None) → dict[str, Any]

Search for albums in the TIDAL catalog.

Parameters:

querystr; positional-only

Search query.

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 matching 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>,
  "totalNumberOfItems": <int>
}

search_artists(query: str, /, country_code: str | None = None, *, limit: int | None = None, offset: int | None = None) → dict[str, Any]

Search for artists in the TIDAL catalog.

Parameters:

querystr; positional-only

Search query.

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 artists to return.

Valid range: 1 to 100.

API default: 10.

offsetint; keyword-only; optional

Index of the first artist to return. Use with limit to get the next batch of artists.

Minimum value: 0.

API default: 0.

Returns:

artistsdict[str, Any]

Page of TIDAL metadata for the matching artists.

Sample response

{
  "items": [
    {
      "artistRoles": [
        {
          "category": <str>,
          "categoryId": <int>
        }
      ],
      "artistTypes": <list[str]>
      "handle": <str>,
      "id": <int>,
      "mixes": {
        "ARTIST_MIX": <str>
      },
      "name": <str>,
      "picture": <str>,
      "popularity": <int>,
      "selectedAlbumCoverFallback": None,
      "spotlighted": <bool>,
      "url": <str>,
      "userId": <int>
    }
  ],
  "limit": <int>,
  "offset": <int>,
  "totalNumberOfItems": <int>
}

search_playlists(query: str, /, country_code: str | None = None, *, limit: int | None = None, offset: int | None = None) → dict[str, Any]

Search for playlists in the TIDAL catalog.

Parameters:

querystr; positional-only

Search query.

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 playlists to return.

Valid range: 1 to 100.

API default: 10.

offsetint; keyword-only; optional

Index of the first playlist to return. Use with limit to get the next batch of playlists.

Minimum value: 0.

API default: 0.

Returns:

playlistsdict[str, Any]

TIDAL catalog information for the matching playlists.

Sample response

{
  "items": [
    {
      "created": <str>,
      "creator": {
        "id": <int>,
        "name": <str>,
        "picture": <str>,
        "selectedAlbumCoverFallback": None,
        "type": <str>
      },
      "customImageUrl": <str>,
      "description": <str>,
      "duration": <int>,
      "image": <str>,
      "lastItemAddedAt": <str>,
      "lastUpdated": <str>,
      "numberOfTracks": <int>,
      "numberOfVideos": <int>,
      "popularity": <int>,
      "promotedArtists": [
        {
          "handle": <str>,
          "id": <int>,
          "name": <str>,
          "picture": <str>,
          "type": "MAIN"
        }
      ],
      "publicPlaylist": <bool>,
      "squareImage": <str>,
      "title": <str>,
      "type": <str>,
      "url": <str>,
      "uuid": <str>
    }
  ],
  "limit": <int>,
  "offset": <int>,
  "totalNumberOfItems": <int>
}

search_tracks(query: str, /, country_code: str | None = None, *, limit: int | None = None, offset: int | None = None) → dict[str, Any]

Search for tracks in the TIDAL catalog.

Parameters:

querystr; positional-only

Search query.

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 tracks to return.

Valid range: 1 to 100.

API default: 10.

offsetint; keyword-only; optional

Index of the first track to return. Use with limit to get the next batch of tracks.

Minimum value: 0.

API default: 0.

Returns:

tracksdict[str, Any]

Page of TIDAL metadata for the matching tracks.

Sample response

{
  "items": [
    {
      "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>
    }
  ],
  "limit": <int>,
  "offset": <int>,
  "totalNumberOfItems": <int>
}

search_videos(query: str, /, country_code: str | None = None, *, limit: int | None = None, offset: int | None = None) → dict[str, Any]

Search for videos in the TIDAL catalog.

Parameters:

querystr; positional-only

Search query.

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 videos to return.

Valid range: 1 to 100.

API default: 10.

offsetint; keyword-only; optional

Index of the first video to return. Use with limit to get the next batch of videos.

Minimum value: 0.

API default: 0.

Returns:

videosdict[str, Any]

Page of TIDAL metadata for the matching videos.

Sample response

{
  "items": [
    {
      "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": <int>,
      "releaseDate": <str>,
      "stemReady": <bool>,
      "streamReady": <bool>,
      "streamStartDate": <str>,
      "title": <str>,
      "trackNumber": <int>,
      "type": "Music Video",
      "vibrantColor": <str>,
      "volumeNumber": <int>
    }
  ],
  "limit": <int>,
  "offset": <int>,
  "totalNumberOfItems": <int>
}