PrivateAPI¶

class minim.qobuz.PrivateAPI(*, app_id: str = None, app_secret: str = None, flow: str = None, browser: bool = False, user_agent: str = None, email: str = None, password: str = None, auth_token: str = None, overwrite: bool = False, save: bool = True)[source]¶

Bases: object

Private Qobuz API client.

The private TIDAL API allows songs, collections (albums, playlists), and performers to be queried, and information about them to be retrieved. As there is no available official documentation for the private Qobuz API, its endpoints have been determined by watching HTTP network traffic.

Attention

As the private Qobuz API is not designed to be publicly accessible, this class can be disabled or removed at any time to ensure compliance with the Qobuz API Terms of Use.

While authentication is not necessary to search for and retrieve data from public content, it is required to access personal content and stream media (with an active Qobuz subscription). In the latter case, requests to the private Qobuz API endpoints must be accompanied by a valid user authentication token in the header.

Minim can obtain user authentication tokens via the password grant, but it is an inherently unsafe method of authentication since it has no mechanisms for multifactor authentication or brute force attack detection. As such, it is highly encouraged that you obtain a user authentication token yourself through the Qobuz Web Player or the Android, iOS, macOS, and Windows applications, and then provide it and its accompanying app ID and secret to this class’s constructor as keyword arguments. The app credentials can also be stored as QOBUZ_PRIVATE_APP_ID and QOBUZ_PRIVATE_APP_SECRET in the operating system’s environment variables, and they will automatically be retrieved.

Tip

The app credentials and user authentication token can be changed or updated at any time using set_flow() and set_auth_token(), respectively.

Minim also stores and manages user authentication tokens and their properties. When the password grant is used to acquire a user authentication token, it is automatically saved to the Minim configuration file to be loaded on the next instantiation of this class. This behavior can be disabled if there are any security concerns, like if the computer being used is a shared device.

Parameters:

app_idstr, keyword-only, optional

App ID. Required if an user authentication token is provided in auth_token.

app_secretstr, keyword-only, optional

App secret. Required if an user authentication token is provided in auth_token.

flowstr, keyword-only, optional

Authorization flow.

Valid values:

"password" for the password flow.
None for no authentication.

browserbool, keyword-only, default: False

Determines whether a web browser is opened with the Qobuz login page using the Playwright framework by Microsoft to complete the password flow. If False, the account email and password must be provided in email and password, respectively.

user_agentstr, keyword-only, optional

User agent information to send in the header of HTTP requests.

emailstr, keyword-only, optional

Account email address. Required if an user authentication token is not provided in auth_token and browser=False.

passwordstr, keyword-only, optional

Account password. Required if an user authentication token is not provided in auth_token and browser=False.

auth_tokenstr, keyword-only, optional

User authentication token. If provided here or found in the Minim configuration file, the authentication process is bypassed.

overwritebool, keyword-only, default: False

Determines whether to overwrite an existing user authentication token in the Minim configuration file.

savebool, keyword-only, default: True

Determines whether newly obtained user authentication tokens and their associated properties are stored to the Minim configuration file.

Attributes:

API_URLstr: URL for the Qobuz API.
WEB_URLstr: URL for the Qobuz Web Player.

Methods

`add_playlist_tracks`	Add tracks to a user playlist.
`check_favorite`	Check whether an item is in the current user's favorites.
`count_search_matches`	Get the counts of catalog search results for a given query.
`create_playlist`	Create a user playlist.
`delete_playlist`	Delete a user playlist.
`delete_playlist_tracks`	Delete tracks from a user playlist.
`favorite_items`	Favorite albums, artists, and/or tracks.
`favorite_playlist`	Subscribe to a playlist.
`get_album`	Get Qobuz catalog information for a single album.
`get_artist`	Get Qobuz catalog information for a single artist.
`get_artist_releases`	Get Qobuz catalog information for an artist's releases.
`get_collection_streams`	Get audio stream data for all tracks in an album or a playlist.
`get_curated_tracks`	Get weekly curated tracks for the user.
`get_favorite_ids`	Get Qobuz IDs of the items in the current user's favorites.
`get_favorites`	Get the current user's favorite albums, artists, and tracks.
`get_featured`	Get Qobuz catalog information for featured albums, artists, articles, and/or playlists.
`get_featured_albums`	Get Qobuz catalog information for featured albums.
`get_featured_playlists`	Get Qobuz catalog information for featured playlists.
`get_genre`	Get Qobuz catalog information for a genre.
`get_genres`	Get Qobuz catalog information for available top-level genres or the subgenres of a specific top-level genre.
`get_label`	Get Qobuz catalog information for a record label.
`get_labels`	Get available labels.
`get_last_updates`	Get the timestamps of the current user's last updates.
`get_personalized_playlist_tracks`	Get Qobuz catalog information for the tracks in a personalized playlist.
`get_personalized_playlists`	Get personalized playlists for the user.
`get_playlist`	Get Qobuz catalog information for a playlist.
`get_playlist_tags`	Get available playlist tags.
`get_profile`	Get the current user's profile information.
`get_purchased_item_ids`	Get the IDs of the current user's purchased albums and tracks.
`get_purchases`	Get the current user's purchases.
`get_similar_artists`	Get Qobuz catalog information for other artists that are similar to an artist.
`get_track`	Get Qobuz catalog information for a track.
`get_track_file_url`	Get the file URL for a track.
`get_track_performers`	Get credits for a track.
`get_track_recommendations`	Get track recommendations based on seed tracks.
`get_track_stream`	Get the audio stream data for a track.
`get_tracks`	Get Qobuz catalog information for multiple tracks.
`get_user_playlists`	Get the current user's custom and favorite playlists.
`move_playlist_tracks`	Move tracks in a user playlist.
`search`	Search Qobuz for media and performers.
`search_albums`	Search for albums in the Qobuz catalog.
`search_artists`	Search for artists in the Qobuz catalog.
`search_most_popular`	Get Qobuz catalog information for the 30 most popular albums, artists, and tracks that match a keyword string.
`search_playlists`	Search for playlists in the Qobuz catalog.
`search_stories`	Search for stories in the Qobuz catalog.
`search_tracks`	Search for tracks in the Qobuz catalog.
`set_auth_token`	Set the private Qobuz API user authentication token.
`set_flow`	Set the authorization flow.
`toggle_favorited`	Toggle the favorited status of an item.
`unfavorite_items`	Unfavorite albums, artists, and/or tracks.
`unfavorite_playlist`	Unsubscribe from a playlist.
`update_playlist`	Update the title, description, and/or privacy of a playlist owned by the current user.
`update_playlist_position`	Organize a user's playlists.

add_playlist_tracks(playlist_id: int | str, track_ids: int | str | list[int | str], *, duplicate: bool = False) → dict[str, Any][source]¶

Add tracks to a user playlist.

User authentication

Requires user authentication via the password flow.

Parameters:

playlist_idint or str

Qobuz user playlist ID.

Example: 17737508.

track_idsint, str, or list

Qobuz track ID(s).

Examples: "24393122,24393138" or [24393122, 24393138].

duplicatebool, keyword-only, default: False

Determines whether duplicate tracks should be added to the playlist.

Returns:

playliststr

Qobuz catalog information for the updated playlist.

Sample response

{
  "id": <int>,
  "name": <str>,
  "description": <str>,
  "tracks_count": <int>,
  "users_count": <int>,
  "duration": <int>,
  "public_at": <int>,
  "created_at": <int>,
  "updated_at": <int>,
  "is_public": <bool>,
  "is_collaborative": <bool>,
  "owner": {
    "id": <int>,
    "name": <str>
  }
}

check_favorite(type: str, item_id: int | str) → dict[str, bool][source]¶

Check whether an item is in the current user’s favorites.

User authentication

Requires user authentication via the password flow.

Parameters:

typestr

Type of item.

Valid values: "album", "artist", "article", "award", "label", "track".

item_idint or str

Qobuz ID of the item.

Returns:

saveddict

Whether the current user has the specified item in their favorites.

Sample response: {"status": <bool>}.

count_search_matches(query: str) → dict[str, dict[str, int]][source]¶

Get the counts of catalog search results for a given query.

Parameters:

querystr: Search query.

Returns:

countsdict

Counts of the search results.

Sample response

{
  "albums": {
    "total": <int>
  },
  "artists": {
    "total": <int>
  },
  "tracks": {
    "total": <int>
  }
}

create_playlist(name: str, *, description: str = None, public: bool = True, collaborative: bool = False) → dict[str, Any][source]¶

Create a user playlist.

User authentication

Requires user authentication via the password flow.

Parameters:

namestr: Qobuz playlist name.
descriptionstr, keyword-only, optional: Brief playlist description.
publicbool, keyword-only, default: True: Determines whether the playlist is public (True) or private (False).
collaborativebool, keyword-only, default: False: Determines whether the playlist is collaborative.

Returns:

playliststr

Qobuz catalog information for the newly created playlist.

Sample response

{
  "id": <int>,
  "name": <str>,
  "description": <str>,
  "tracks_count": <int>,
  "users_count": <int>,
  "duration": <int>,
  "public_at": <int>,
  "created_at": <int>,
  "updated_at": <int>,
  "is_public": <bool>,
  "is_collaborative": <bool>,
  "owner": {
    "id": <int>,
    "name": <str>
  }
}

delete_playlist(playlist_id: int | str) → None[source]¶

Delete a user playlist.

User authentication

Requires user authentication via the password flow.

Parameters:

playlist_idint or str

Qobuz user playlist ID.

Example: 17737508.

delete_playlist_tracks(playlist_id: int | str, playlist_track_ids: int | str | list[int | str]) → dict[str, Any][source]¶

Delete tracks from a user playlist.

User authentication

Requires user authentication via the password flow.

Parameters:

playlist_idint or str

Qobuz user playlist ID.

Example: 17737508.

playlist_track_idsint, str, or list

Qobuz playlist track ID(s).

Note

Playlist track IDs are not the same as track IDs. To get playlist track IDs, use get_playlist().

Returns:

playliststr

Qobuz catalog information for the updated playlist.

Sample response

{
  "id": <int>,
  "name": <str>,
  "description": <str>,
  "tracks_count": <int>,
  "users_count": <int>,
  "duration": <int>,
  "public_at": <int>,
  "created_at": <int>,
  "updated_at": <int>,
  "is_public": <bool>,
  "is_collaborative": <bool>,
  "owner": {
    "id": <int>,
    "name": <str>
  }
}

Favorite albums, artists, and/or tracks.

User authentication

Requires user authentication via the password flow.

See also

For playlists, use favorite_playlist().

Parameters:

album_idsstr or list, keyword-only, optional: Qobuz album ID(s).
artist_idsint, str, or list, keyword-only, optional: Qobuz artist ID(s).
track_idsint, str, or list, keyword-only, optional: Qobuz track ID(s).

favorite_playlist(playlist_id: int | str) → None[source]¶

Subscribe to a playlist.

User authentication

Requires user authentication via the password flow.

Parameters:

playlist_idint or str

Qobuz playlist ID.

Example: 15732665.

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

Get Qobuz catalog information for a single album.

Parameters:

album_idstr

Qobuz album ID.

Example: "0060254735180".

extrasstr or list, keyword-only, optional

Specifies extra information about the album to return.

Valid values: "albumsFromSameArtist", "focus", "focusAll".

limitint, keyword-only, optional

Maximum number of tracks to return.

Valid range: 1 to 500.

API default: 500.

offsetint, keyword-only, optional

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

Minimum value: 0.

API default: 0.

Returns:

albumdict

Qobuz catalog information for a single album.

Sample response

{
  "maximum_bit_depth": <int>,
  "image": {
    "small": <str>,
    "thumbnail": <str>,
    "large": <str>,
    "back": <str>
  },
  "media_count": <str>,
  "artist": {
    "image": <str>,
    "name": <str>,
    "id": <int>,
    "albums_count": <int>,
    "slug": <str>,
    "picture": <str>
  },
  "artists": [
    {
      "id": <int>,
      "name": <str>,
      "roles": [<str>]
    }
  ],
  "upc": <str>,
  "released_at": <int>,
  "label": {
    "name": <str>,
    "id": <int>,
    "albums_count": <int>,
    "supplier_id": <int>,
    "slug": <str>
  },
  "title": <str>,
  "qobuz_id": <int>,
  "version": <str>,
  "url": <str>,
  "duration": <int>,
  "parental_warning": <bool>,
  "popularity": <int>,
  "tracks_count": <int>,
  "genre": {
    "path": [<int>],
    "color": <str>,
    "name": <str>,
    "id": <int>,
    "slug": <str>
  },
  "maximum_channel_count": <int>,
  "id": <str>,
  "maximum_sampling_rate": <int>,
  "articles": <list>,
  "release_date_original": <str>,
  "release_date_download": <str>,
  "release_date_stream": <str>,
  "purchasable": <bool>,
  "streamable": <bool>,
  "previewable": <bool>,
  "sampleable": <bool>,
  "downloadable": <bool>,
  "displayable": <bool>,
  "purchasable_at": <int>,
  "streamable_at": <int>,
  "hires": <bool>,
  "hires_streamable": <bool>,
  "awards": <list>,
  "description": <str>,
  "description_language": <str>,
  "goodies": <list>,
  "area": <str>,
  "catchline": <str>,
  "composer": {
    "id": <int>,
    "name": <str>,
    "slug": <str>,
    "albums_count": <int>,
    "picture": <str>,
    "image": <str>
  },
  "created_at": <int>,
  "genres_list": [<str>],
  "period": <str>,
  "copyright": <str>,
  "is_official": <bool>,
  "maximum_technical_specifications": <str>,
  "product_sales_factors_monthly": <int>,
  "product_sales_factors_weekly": <int>,
  "product_sales_factors_yearly": <int>,
  "product_type": <str>,
  "product_url": <str>,
  "recording_information": <str>,
  "relative_url": <str>,
  "release_tags": <list>,
  "release_type": <str>,
  "slug": <str>,
  "subtitle": <str>,
  "tracks": {
    "offset": <int>,
    "limit": <int>,
    "total": <int>,
    "items": [
      {
        "maximum_bit_depth": <int>,
        "copyright": <str>,
        "performers": <str>,
        "audio_info": {
          "replaygain_track_peak": <float>,
          "replaygain_track_gain": <float>
        },
        "performer": {
          "name": <str>,
          "id": <int>
        },
        "work": <str>,
        "composer": {
          "name": <str>,
          "id": <int>
        },
        "isrc": <str>,
        "title": <str>,
        "version": <str>,
        "duration": <int>,
        "parental_warning": <bool>,
        "track_number": <int>,
        "maximum_channel_count": <int>,
        "id": <int>,
        "media_number": <int>,
        "maximum_sampling_rate": <int>,
        "release_date_original": <str>,
        "release_date_download": <str>,
        "release_date_stream": <str>,
        "release_date_purchase": <str>,
        "purchasable": <bool>,
        "streamable": <bool>,
        "previewable": <bool>,
        "sampleable": <bool>,
        "downloadable": <bool>,
        "displayable": <bool>,
        "purchasable_at": <int>,
        "streamable_at": <int>,
        "hires": <bool>,
        "hires_streamable": <bool>
      }
    ]
  }
}

get_artist(artist_id: int | str, *, extras: str | list[str] = None, limit: int = None, offset: int = None) → dict[str, Any][source]¶

Get Qobuz catalog information for a single artist.

Parameters:

artist_idint or str

Qobuz artist ID.

extrasstr or list, keyword-only, optional

Specifies extra information about the artist to return.

Valid values: "albums", "tracks", "playlists", "tracks_appears_on", and "albums_with_last_release".

limitint, keyword-only, optional

The maximum number of extra items to return. Has no effect if extras=None.

Default: 25.

offsetint, keyword-only, optional

The index of the first extra item to return. Use with limit to get the next page of extra items. Has no effect if extras=None.

Default: 0.

Returns:

artistdict

Qobuz catalog information for a single artist.

Sample response

{
  "id": <int>,
  "name": <str>,
  "albums_as_primary_artist_count": <int>,
  "albums_as_primary_composer_count": <int>,
  "albums_count": <int>,
  "slug": <str>,
  "picture": <str>,
  "image": {
    "small": <str>,
    "medium": <str>,
    "large": <str>,
    "extralarge": <str>,
    "mega": <str>
  },
  "similar_artist_ids": [<int>],
  "information": <str>,
  "biography": {
    "summary": <str>,
    "content": <str>,
    "source": <str>,
    "language": <str>
  }
}

get_artist_releases(artist_id: int | str, *, release_types: str | list[str] = None, filters: str | list[str] = None, limit: int = None, offset: int = None, order: str = None, order_direction: str = None, include_tracks: bool = False, track_limit: int = None) → dict[str, Any][source]¶

Get Qobuz catalog information for an artist’s releases.

User authentication

Requires user authentication via the password flow.

Parameters:

artist_idint or str

Qobuz artist ID.

release_typesstr or list, keyword-only, optional

Release types to include in the response.

Valid values: "all", "album", "live", "compilation", "epSingle", "other", "download", "composer".

filtersstr or list, keyword-only, optional

Content filters to apply to the releases.

Valid values: "hires", "explicit".

limitint, keyword-only, optional

The maximum number of releases to return.

Default: 50.

offsetint, keyword-only, optional

The index of the first release to return. Use with limit to get the next page of releases.

Default: 0.

orderstr, keyword-only, optional

Field to sort the releases by.

Valid values: "relevant", "release_date".

order_directionstr, keyword-only, optional

Order to sort in.

Valid values: "asc", "desc".

include_tracksbool, keyword-only, default: False

Whether to include tracks in the response.

track_limitint, keyword-only, optional

The maximum number of tracks to include per release when include_tracks is True.

Default: 10.

Returns:

releasesdict

Qobuz catalog information for the artist’s releases.

Sample response

{
  "has_more": <bool>,
  "items": [
    {
      "artist": {
        "id": <int>,
        "name": {
          "display": <str>
        }
      },
      "artists": [
        {
          "id": <int>,
          "name": <str>,
          "roles": <list[str]>
        }
      ],
      "audio_info": {
        "maximum_bit_depth": <int>,
        "maximum_channel_count": <int>,
        "maximum_sampling_rate": <float>
      },
      "awards": [],
      "dates": {
        "download": <str>,
        "original": <str>,
        "stream": <str>,
      },
      "duration": <int>,
      "genre": {
        "id": <int>,
        "name": <str>,
        "path": <list[int]>,
      },
      "id": <str>,
      "image": {
        "large": <str>,
        "small": <str>,
        "thumbnail": <str>
      },
      "label": {
        "id": <int>,
        "name": <str>
      },
      "parental_warning": <bool>,
      "release_tags": [],
      "release_type": <str>,
      "rights": {
        "downloadable": <bool>,
        "hires_purchasable": <bool>,
        "hires_streamable": <bool>,
        "purchasable": <bool>,
        "streamable": <bool>
      },
      "title": <str>,
      "tracks": {
        "has_more": <bool>,
        "items": [
          {
            "artist": {
              "id": <int>,
              "name": {
                "display": <str>
              }
            },
            "artists": [],
            "audio_info": {
              "maximum_bit_depth": <int>,
              "maximum_channel_count": <int>,
              "maximum_sampling_rate": <float>
            },
            "composer": {
              "id": <int>,
              "name": <str>,
            },
            "duration": <int>,
            "id": <int>,
            "isrc": <str>,
            "parental_warning": <bool>,
            "physical_support": {
              "media_number": <int>,
              "track_number": <int>
            },
            "rights": {
              "downloadable": <bool>,
              "hires_purchasable": <bool>,
              "hires_streamable": <bool>,
              "previewable": <bool>,
              "purchasable": <bool>,
              "sampleable": <bool>,
              "streamable": <bool>
            },
            "title": <str>,
            "version": <str>,
            "work": None
          }
        ]
      },
      "tracks_count": <int>,
      "version": <str>,
    }
  ]
}

get_collection_streams(id: int | str, type: str, *, format_id: int | str = 27) → list[tuple[bytes, str]][source]¶

Get audio stream data for all tracks in an album or a playlist.

Subscription

Full track playback information and lossless and Hi-Res audio is only available with an active Qobuz subscription.

Note

This method is provided for convenience and is not a private Qobuz API endpoint.

Parameters:

idint or str

Qobuz collection ID.

typestr

Collection type.

Valid values: "album" and "playlist".

format_idint, default: 27

Audio format ID that determines the maximum audio quality.

Valid values:

5 for constant bitrate (320 kbps) MP3.
6 for CD-quality (16-bit, 44.1 kHz) FLAC.
7 for up to 24-bit, 96 kHz Hi-Res FLAC.
27 for up to 24-bit, 192 kHz Hi-Res FLAC.

Returns:

streamslist: Audio stream data.

get_curated_tracks() → list[dict[str, Any]][source]¶

Get weekly curated tracks for the user.

User authentication

Requires user authentication via the password flow.

Parameters:

limitint, keyword-only, optional

The maximum number of tracks to return.

Default: 50.

offsetint, keyword-only, optional

The index of the first track to return. Use with limit to get the next page of tracks.

Default: 0.

Returns:

trackslist

Qobuz catalog information for the curated tracks.

Sample response

{
  "title": <str>,
  "baseline": <str>,
  "description": <str>,
  "type": "weekly",
  "step_pagination": <int>,
  "images": {
    "small": <str>,
    "large": <str>
  },
  "graphics": {
    "background": <str>,
    "foreground": <str>
  },
  "duration": <int>,
  "generated_at": <int>,
  "expires_on": <int>,
  "track_count": <int>,
  "tracks": {
    "offset": <int>,
    "limit": <int>,
    "items": [
      {
        "maximum_bit_depth": <int>,
        "copyright": <str>,
        "performers": <str>,
        "audio_info": {
          "replaygain_track_peak": <float>,
          "replaygain_track_gain": <float>
        },
        "performer": {
          "name": <str>,
          "id": <int>
        },
        "album": {
          "image": {
            "small": <str>,
            "thumbnail": <str>,
            "large": <str>
          },
          "maximum_bit_depth": <int>,
          "media_count": <int>,
          "artist": {
            "image": <str>,
            "name": <str>,
            "id": <int>,
            "albums_count": <int>,
            "slug":<str>,
            "picture": <str>
          },
          "upc": <str>,
          "released_at": <int>,
          "label": {
            "name": <str>,
            "id": <int>,
            "albums_count": <int>,
            "supplier_id": <int>,
            "slug": <str>
          },
          "title": <str>,
          "qobuz_id": <int>,
          "version": <str>,
          "duration": <int>,
          "parental_warning": <bool>,
          "tracks_count": <int>,
          "popularity": <int>,
          "genre": {
            "path": [<int>],
            "color": <str>,
            "name": <str>,
            "id": <int>,
            "slug": <str>
          },
          "maximum_channel_count": <int>,
          "id": <str>,
          "maximum_sampling_rate": <int>,
          "previewable": <bool>,
          "sampleable": <bool>,
          "displayable": <bool>,
          "streamable": <bool>,
          "streamable_at": <int>,
          "downloadable": <bool>,
          "purchasable_at": <int>,
          "purchasable": <bool>,
          "release_date_original": <str>,
          "release_date_download": <str>,
          "release_date_stream": <str>,
          "release_date_purchase": <str>,
          "hires": <bool>,
          "hires_streamable": <bool>
        },
        "work": <str>,
        "composer": {
          "name": <str>,
          "id": <int>
        },
        "isrc": <str>,
        "title": <str>,
        "version": <str>,
        "duration": <int>,
        "parental_warning": <bool>,
        "track_number": <int>,
        "maximum_channel_count": <int>,
        "id": <int>,
        "media_number": <int>,
        "maximum_sampling_rate": <int>,
        "release_date_original": <str>,
        "release_date_download": <str>,
        "release_date_stream": <str>,
        "release_date_purchase": <str>,
        "purchasable": <bool>,
        "streamable": <bool>,
        "previewable": <bool>,
        "sampleable": <bool>,
        "downloadable": <bool>,
        "displayable": <bool>,
        "purchasable_at": <int>,
        "streamable_at": <int>,
        "hires": <bool>,
        "hires_streamable": <bool>
      }
    ]
  }
}

get_favorite_ids() → dict[str, Any][source]¶

Get Qobuz IDs of the items in the current user’s favorites.

User authentication

Requires user authentication via the password flow.

Returns:

saved_idsdict

Qobuz IDs of the items in the user’s favorites.

Sample response

{
  "albums": <list[str]>,
  "articles": [],
  "artists": <list[int]>,
  "awards": [],
  "labels": [],
  "tracks": <list[int]>,
}

get_favorites(type: str = None, *, limit: int = None, offset: int = None) → dict[str, dict][source]¶

Get the current user’s favorite albums, artists, and tracks.

User authentication

Requires user authentication via the password flow.

Parameters:

typestr

Media type to return. If not specified, all of the user’s favorite items are returned.

Valid values: "albums", "artists", and "tracks".

limitint, keyword-only, optional

The maximum number of favorited items to return.

Default: 50.

offsetint, keyword-only, optional

The index of the first favorited item to return. Use with limit to get the next page of favorited items.

Default: 0.

Returns:

favoritesdict

A dictionary containing Qobuz catalog information for the current user’s favorite items and the user’s ID and email.

Sample response

{
  "albums": {
    "offset": <int>,
    "limit": <int>,
    "total": <int>,
    "items": <list>
  },
  "user": {
    "id": <int>,
    "login": <str>
  }
}

get_featured(type: str = None, genre_ids: int | str | list[int | str] = None, *, limit: int = None, offset: int = None) → dict[str, Any][source]¶

Get Qobuz catalog information for featured albums, artists, articles, and/or playlists.

Parameters:

typestr, optional

Type of item to return. If not specified, featured items of all types are returned.

Valid values: "albums", "articles", "artists", "playlists".

genre_idsint, str, or list, optional

Qobuz IDs of the genres used to filter the featured items to return.

Examples: 10, "64", "10,64", [10, "64"].

limitint, keyword-only, optional

The maximum number of items to return per item type.

Default: 25.

offsetint, keyword-only, optional

The index of the first item to return per item type. Use with limit to get the next page of items.

Default: 0.

Returns:

itemsdict

Qobuz catalog information for the featured items.

Sample response

{
  "albums": {
    "items": [
      {
        "articles": [],
        "artist": {
          "albums_count": <int>,
          "id": <int>,
          "image": None,
          "name": <str>,
          "picture": None,
          "slug": <str>
        },
        "artists": [
          {
            "id": <int>,
            "name": <str>,
            "roles": <list[str]>
          }
        ],
        "displayable": <bool>,
        "downloadable": <bool>,
        "duration": <int>,
        "genre": {
          "color": <str>,
          "id": <int>,
          "name": <str>,
          "path": <list[int]>,
          "slug": <str>
        },
        "hires": <bool>,
        "hires_streamable": <bool>,
        "id": <str>,
        "image": {
          "back": None,
          "large": <str>,
          "small": <str>,
          "thumbnail": <str>
        },
        "label": {
          "albums_count": <int>,
          "id": <int>,
          "name": <str>,
          "slug": <str>,
          "supplier_id": <int>
        },
        "maximum_bit_depth": <int>,
        "maximum_channel_count": <int>,
        "maximum_sampling_rate": <float>,
        "media_count": <int>,
        "parental_warning": <bool>,
        "popularity": <int>,
        "previewable": <bool>,
        "purchasable": <bool>,
        "purchasable_at": <int>,
        "qobuz_id": <int>,
        "release_date_download": <str>,
        "release_date_original": <str>,
        "release_date_stream": <str>,
        "released_at": <int>,
        "sampleable": <bool>,
        "slug": <str>,
        "streamable": <bool>,
        "streamable_at": <int>,
        "title": <str>,
        "tracks_count": <int>,
        "upc": <str>,
        "url": <str>,
        "version": <str>
      }
    ],
    "limit": <int>,
    "offset": <int>,
    "total": <int>
  },
  "artists": {
    "items": [
      {
        "albums_count": <int>,
        "id": <int>,
        "image": {
          "extralarge": <str>,
          "large": <str>,
          "medium": <str>,
          "mega": <str>,
          "small": <str>
        },
        "name": <str>,
        "picture": <str>,
        "slug": <str>
      }
    ],
    "limit": <int>,
    "offset": <int>,
    "total": <int>
  },
  "playlists": {
    "items": [
      {
        "created_at": <int>,
        "description": <str>,
        "duration": <int>,
        "featured_artists": [],
        "genres": [
          {
            "color": <str>,
            "id": <int>,
            "name": <str>,
            "path": <list[int]>,
            "percent": <int>,
            "slug": <str>
          }
        ],
        "id": <int>,
        "image_rectangle": <list[str]>,
        "image_rectangle_mini": <list[str]>,
        "images": <list[str]>,
        "images150": <list[str]>,
        "images300": <list[str]>,
        "is_collaborative": <bool>,
        "is_featured": <bool>,
        "is_public": <bool>,
        "name": <str>,
        "owner": {
          "id": <int>,
          "name": <str>
        },
        "public_at": <int>,
        "slug": <str>,
        "stores": <list[str]>,
        "tags": [
          {
            "color": <str>,
            "featured_tag_id": <str>,
            "genre_tag": None,
            "is_discover": <bool>,
            "name_json": <str>,
            "slug": <str>
          }
        ],
        "tracks_count": <int>,
        "updated_at": <int>,
        "users_count": <int>
      }
    ],
    "limit": <int>,
    "offset": <int>,
    "total": <int>
  }
}

get_featured_albums(type: str = 'new-releases', *, genre_ids: int | str | list[int | str] = None, limit: int = None, offset: int = None) → dict[str, Any][source]¶

Get Qobuz catalog information for featured albums.

Parameters:

typestr, default: "new-releases"

Feature type.

Valid values: "best-sellers", "editor-picks", "ideal-discography", "most-featured", "most-streamed", "new-releases", "new-releases-full", "press-awards", "recent-releases", "qobuzissims", "harmonia-mundi", "universal-classic", "universal-jazz", "universal-jeunesse", and "universal-chanson".

genre_idsint, str, or list, optional

Qobuz IDs of the genres used to filter the featured albums to return.

Examples: 10, "64", "10,64", [10, "64"].

limitint, keyword-only, optional

The maximum number of albums to return.

Default: 50.

offsetint, keyword-only, optional

The index of the first album to return. Use with limit to get the next page of albums.

Default: 0.

Returns:

albumsdict

Qobuz catalog information for the albums.

Sample response

{
  "albums": {
    "total": <int>,
    "limit": <int>,
    "offset": <int>,
    "items": [
      {
        "maximum_bit_depth": <int>,
        "image": {
          "small": <str>,
          "thumbnail": <str>,
          "large": <str>,
          "back": <str>
        },
        "media_count": <str>,
        "artist": {
          "image": <str>,
          "name": <str>,
          "id": <int>,
          "albums_count": <int>,
          "slug": <str>,
          "picture": <str>
        },
        "artists": [
          {
            "id": <int>,
            "name": <str>,
            "roles": [<str>]
          }
        ],
        "upc": <str>,
        "released_at": <int>,
        "label": {
          "name": <str>,
          "id": <int>,
          "albums_count": <int>,
          "supplier_id": <int>,
          "slug": <str>
        },
        "title": <str>,
        "qobuz_id": <int>,
        "version": <str>,
        "url": <str>,
        "duration": <int>,
        "parental_warning": <bool>,
        "popularity": <int>,
        "tracks_count": <int>,
        "genre": {
          "path": [<int>],
          "color": <str>,
          "name": <str>,
          "id": <int>,
          "slug": <str>
        },
        "maximum_channel_count": <int>,
        "id": <str>,
        "maximum_sampling_rate": <int>,
        "articles": <list>,
        "release_date_original": <str>,
        "release_date_download": <str>,
        "release_date_stream": <str>,
        "purchasable": <bool>,
        "streamable": <bool>,
        "previewable": <bool>,
        "sampleable": <bool>,
        "downloadable": <bool>,
        "displayable": <bool>,
        "purchasable_at": <int>,
        "streamable_at": <int>,
        "hires": <bool>,
        "hires_streamable": <bool>
      }
    ]
  }
}

get_featured_playlists(type: str = 'editor-picks', *, limit: int = None, offset: int = None) → dict[str, Any][source]¶

Get Qobuz catalog information for featured playlists.

Parameters:

typestr, default: "editor-picks"

Feature type.

Valid values: "editor-picks" and "last-created".

limitint, keyword-only, optional

The maximum number of playlists to return.

Default: 50.

offsetint, keyword-only, optional

The index of the first playlist to return. Use with limit to get the next page of playlists.

Default: 0.

Returns:

playlistsdict

Qobuz catalog information for the playlists.

Sample response

{
  "offset": <int>,
  "limit": <int>,
  "total": <int>,
  "items": [
    {
      "owner": {
        "name": <str>,
        "id": <int>
      },
      "image_rectangle_mini": [<str>],
      "users_count": <int>,
      "images150": [<str>],
      "images": [<str>],
      "featured_artists": <list>,
      "is_collaborative": <bool>,
      "stores": [<str>],
      "description": <str>,
      "created_at": <int>,
      "images300": [<str>],
      "tags": [
        {
          "color": <str>,
          "is_discover": <bool>,
          "featured_tag_id": <str>,
          "name_json": <str>,
          "slug": <str>,
          "genre_tag": <str>
        }
      ],
      "duration": <int>,
      "updated_at": <int>,
      "genres": [
        {
          "path": [<int>],
          "color": <str>,
          "name": <str>,
          "id": <int>,
          "percent": <float>,
          "slug": <str>
        }
      ],
      "image_rectangle": [<str>],
      "tracks_count": <int>,
      "public_at": <int>,
      "name": <str>,
      "is_public": <bool>,
      "id": <int>,
      "slug": <str>,
      "is_featured": <bool>
    }
  ]
}

get_genre(genre_id: int | str) → dict[str, Any][source]¶

Get Qobuz catalog information for a genre.

Parameters:

genre_idint or str

Qobuz genre ID.

Example: 10.

Returns:

genredict

Qobuz catalog information for the genre.

Sample

{
  "color": <str>,
  "id": <int>,
  "name": <str>,
  "path": [<int>],
  "slug": <str>
}

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

Get Qobuz catalog information for available top-level genres or the subgenres of a specific top-level genre.

Parameters:

genre_idint or str, optional

Qobuz ID of the top-level genre. If not provided, all top-level genres are returned.

Examples: 10, "64".

limitint, keyword-only, optional

Maximum number of genres to return.

Valid range: 1 to 500.

API default: 25.

offsetint, keyword-only, optional

Index of the first genre to return. Use with limit to get the next batch of genres.

Minimum value: 0.

API default: 0.

Returns:

genresdict

Qobuz catalog information for the genres.

Sample response

{
  "genres": {
    "items": [
      {
        "color": <str>,
        "id": <int>,
        "name": <str>,
        "path": <list[int]>,
        "slug": <str>
      }
    ],
    "limit": <int>,
    "offset": <int>,
    "total": <int>
  },
  "parent": {
    "color": <str>,
    "id": <int>,
    "name": <str>,
    "path": <list[int]>,
    "slug": <str>
  }
}

get_label(label_id: int | str, *, extras: str | list[str] = None, limit: int = None, offset: int = None) → dict[str, Any][source]¶

Get Qobuz catalog information for a record label.

Parameters:

label_idint or str

Qobuz record label ID.

Example: 1153.

extrasstr or list, keyword-only, optional

Related resources to include metadata for in the response.

Valid values: "albums", "focus", "focusAll".

limitint, keyword-only, optional

The maximum number of albums to return. Has no effect if albums=False.

Default: 25.

offsetint, keyword-only, optional

The index of the first album to return. Use with limit to get the next page of albums. Has no effect if albums=False.

Default: 0.

Returns:

labeldict

Qobuz catalog information for the record label.

Sample response

{
  "id": <int>,
  "name": <str>,
  "slug": <str>,
  "supplier_id": <int>,
  "albums_count": <int>,
  "image": <str>,
  "description": <str>
}

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

Get available labels.

Parameters:

limitint, keyword-only, optional

The maximum number of labels to return.

Default: 25.

offsetint, keyword-only, optional

The index of the first label to return. Use with limit to get the next page of labels.

Default: 0.

Returns:

labelsdict

Qobuz catalog information for the labels.

Sample response

{
  "labels": {
    "items": [
      {
        "albums_count": <int>,
        "id": <int>,
        "name": <str>,
        "slug": <str>,
        "supplier_id": <int>,
      }
    ],
    "limit": <int>,
    "offset": <int>,
    "total": <int>
  }
}

get_last_updates() → dict[str, Any][source]¶

Get the timestamps of the current user’s last updates.

User authentication

Requires user authentication via the password flow.

Returns:

last_updatesdict

The timestamps of the current user’s last updates for their favorites, playlists, and purchases.

Sample response

{
  "last_update":{
    "favorite": <int>,
    "favorite_album": <int>,
    "favorite_artist": <int>,
    "favorite_track": <int>,
    "playlist": <int>,
    "purchase": <int>
  }
}

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

Get Qobuz catalog information for the tracks in a personalized playlist.

User authentication

Requires user authentication via the password flow.

Parameters:

playlist_typestr

Type of personalized playlist.

Example: "weekly".

limitint, keyword-only, optional

Maximum number of items to return. Only applicable when playlist_type is not "weekly".

Valid range: 1 to 500.

API default: 50.

offsetint, keyword-only, optional

Index of the first item to return. Use with limit to get the next batch of items. Only applicable when playlist_type is not "weekly".

Minimum value: 0.

API default: 0.

Returns:

tracksdict

Qobuz catalog information for tracks in the personally curated playlist.

Sample response

{
  "baseline": <str>,
  "description": <str>,
  "duration": <int>,
  "expires_on": <int>,
  "generated_at": <int>,
  "graphics": {
    "background": <str>,
    "foreground": <str>
  },
  "images": {
    "large": <str>,
    "small": <str>
  },
  "step_pagination": <int>,
  "title": <str>,
  "track_count": <int>,
  "tracks": {
    "items": [
      {
        "album": {
          "artist": {
            "albums_count": <int>,
            "id": <int>,
            "image": None,
            "name": <str>,
            "picture": None,
            "slug": <str>
          },
          "displayable": <bool>,
          "downloadable": <bool>,
          "genre": {
            "id": <int>,
            "name": <str>,
            "path": <list[int]>,
            "slug": <str>
          },
          "hires": <bool>,
          "hires_streamable": <bool>,
          "id": <str>,
          "image": {
            "large": <str>,
            "small": <str>,
            "thumbnail": <str>
          },
          "label": {
            "albums_count": <int>,
            "id": <int>,
            "name": <str>,
            "slug": <str>,
            "supplier_id": <int>
          },
          "maximum_bit_depth": <int>,
          "maximum_channel_count": <int>,
          "maximum_sampling_rate": <float>,
          "previewable": <bool>,
          "purchasable": <bool>,
          "purchasable_at": <str>,
          "qobuz_id": <int>,
          "release_date_download": <str>,
          "release_date_original": <str>,
          "release_date_purchase": <str>,
          "release_date_stream": <str>,
          "released_at": <int>,
          "sampleable": <bool>,
          "streamable": <bool>,
          "streamable_at": <int>,
          "title": <str>,
          "version": <str>
        },
        "audio_info": {
          "replaygain_track_gain": <float>,
          "replaygain_track_peak": <float>
        },
        "composer": {
          "id": <int>,
          "name": <str>
        },
        "copyright": <str>,
        "displayable": <bool>,
        "downloadable": <bool>,
        "duration": <int>,
        "hires": <bool>,
        "hires_streamable": <bool>,
        "id": <int>,
        "isrc": <str>,
        "maximum_bit_depth": <int>,
        "maximum_channel_count": <int>,
        "maximum_sampling_rate": <float>,
        "parental_warning": <bool>,
        "performer": {
          "id": <int>,
          "name": <str>,
        },
        "performers": <str>,
        "position": <int>,
        "previewable": <bool>,
        "purchasable": <bool>,
        "purchasable_at": <int>,
        "release_date_download": <str>,
        "release_date_original": <str>,
        "release_date_purchase": <str>,
        "release_date_stream": <str>,
        "sampleable": <bool>,
        "streamable": <bool>,
        "streamable_at": <int>,
        "title": <str>,
        "version": <str>,
        "work": None
      }
    ],
    "limit": <int>,
    "offset": <int>
  },
  "type": <str>
}

get_personalized_playlists() → list[dict[str, Any]][source]¶

Get personalized playlists for the user.

User authentication

Requires user authentication via the password flow.

Returns:

playlistslist

Qobuz catalog information for the personalized playlists.

Sample response

[
  {
    "baseline": <str>,
    "description": <str>,
    "graphics": {
      "background": <str>,
      "foreground": <str>
    },
    "images": {
      "large": <str>,
      "small": <str>
    },
    "step_pagination": <int>,
    "title": <str>,
    "type": <str>
  }
]

get_playlist(playlist_id: int | str, *, tracks: bool = True, limit: int = None, offset: int = None) → dict[str, Any][source]¶

Get Qobuz catalog information for a playlist.

Parameters:

playlist_idint or str

Qobuz playlist ID.

Example: 15732665.

tracksbool, keyword-only, default: True

Specifies whether information on the tracks in the playlist is returned.

limitint, keyword-only, optional

The maximum number of tracks to return. Has no effect if tracks=False.

Default: 50.

offsetint, keyword-only, optional

The index of the first track to return. Use with limit to get the next page of tracks. Has no effect if tracks=False.

Default: 0.

Returns:

playlistdict

Qobuz catalog information for the playlist.

Sample response

{
  "image_rectangle_mini": [<str>],
  "featured_artists": <list>,
  "description": <str>,
  "created_at": <int>,
  "timestamp_position": <int>,
  "images300": [<str>],
  "duration": <int>,
  "updated_at": <int>,
  "genres": [
    {
      "id": <int>,
      "color": <str>,
      "name": <str>,
      "path": [<int>],
      "slug": <str>,
      "percent": <float>
    }
  ],
  "image_rectangle": [<str>],
  "id": <int>,
  "slug": <str>,
  "owner": {
    "id": <int>,
    "name": <str>
  },
  "users_count": <int>,
  "images150": [<str>],
  "images": [<str>],
  "is_collaborative": <bool>,
  "stores": [<str>],
  "tags": [
    {
      "featured_tag_id": <str>,
      "name_json": <str>,
      "slug": <str>,
      "color": <str>,
      "genre_tag": <str>,
      "is_discover": <bool>
    }
  ],
  "tracks_count": <int>,
  "public_at": <int>,
  "name": <str>,
  "is_public": <bool>,
  "is_featured": <bool>,
  "tracks": {
    "offset": <int>,
    "limit": <int>,
    "total": <int>,
    "items": [
      {
        "maximum_bit_depth": <int>,
        "copyright": <str>,
        "performers": <str>,
        "audio_info": {
          "replaygain_track_peak": <float>,
          "replaygain_track_gain": <float>
        },
        "performer": {
          "name": <str>,
          "id": <int>
        },
        "album": {
          "image": {
            "small": <str>,
            "thumbnail": <str>,
            "large": <str>
          },
          "maximum_bit_depth": <int>,
          "media_count": <int>,
          "artist": {
            "image": <str>,
            "name": <str>,
            "id": <int>,
            "albums_count": <int>,
            "slug": <str>,
            "picture": <str>
          },
          "upc": <str>,
          "released_at": <int>,
          "label": {
            "name": <str>,
            "id": <int>,
            "albums_count": <int>,
            "supplier_id": <int>,
            "slug": <str>
          },
          "title": <str>,
          "qobuz_id": <int>,
          "version": <str>,
          "duration": <int>,
          "parental_warning": <bool>,
          "tracks_count": <int>,
          "popularity": <int>,
          "genre": {
            "path": [<int>],
            "color": <str>,
            "name": <str>,
            "id": <int>,
            "slug": <str>
          },
          "maximum_channel_count": <int>,
          "id": <str>,
          "maximum_sampling_rate": <int>,
          "previewable": <bool>,
          "sampleable": <bool>,
          "displayable": <bool>,
          "streamable": <bool>,
          "streamable_at": <int>,
          "downloadable": <bool>,
          "purchasable_at": <int>,
          "purchasable": <bool>,
          "release_date_original": <str>,
          "release_date_download": <str>,
          "release_date_stream": <str>,
          "release_date_purchase": <str>,
          "hires": <bool>,
          "hires_streamable": <bool>
        },
        "work": <str>,
        "isrc": <str>,
        "title": <str>,
        "version": null,
        "duration": <int>,
        "parental_warning": <bool>,
        "track_number": <int>,
        "maximum_channel_count": <int>,
        "id": <int>,
        "media_number": <int>,
        "maximum_sampling_rate": <int>,
        "release_date_original": <str>,
        "release_date_download": <str>,
        "release_date_stream": <str>,
        "release_date_purchase": <str>,
        "purchasable": <bool>,
        "streamable": <bool>,
        "previewable": <bool>,
        "sampleable": <bool>,
        "downloadable": <bool>,
        "displayable": <bool>,
        "purchasable_at": <int>,
        "streamable_at": <int>,
        "hires": <bool>,
        "hires_streamable": <bool>,
        "position": <int>,
        "created_at": <int>,
        "playlist_track_id": <int>
      }
    ]
  }
}

get_playlist_tags() → dict[str, list[dict[str, Any]]][source]¶

Get available playlist tags.

Returns:

playlist_tagsdict

Qobuz catalog information for playlist tags.

Sample response

{
  "tags": [
    {
      "color": <str>,
      "featured_tag_id": <str>,
      "genre_tag": None,
      "is_discover": <str>,
      "name_json": <str>,
      "position": <str>,
      "slug": <str>
    }
  ]
}

get_profile() → dict[str, Any][source]¶

Get the current user’s profile information.

User authentication

Requires user authentication via the password flow.

Returns:

profiledict

A dictionary containing the current user’s profile information.

Sample response

{
  "id": <int>,
  "publicId": <str>,
  "email": <str>,
  "login": <str>,
  "firstname": <str>,
  "lastname": <str>,
  "display_name": <str>,
  "country_code": <str>,
  "language_code": <str>,
  "zone": <str>,
  "store": <str>,
  "country": <str>,
  "avatar": <str>,
  "genre": <str>,
  "age": <int>,
  "creation_date": <str>,
  "subscription": {
    "offer": <str>,
    "periodicity": <str>,
    "start_date": <str>,
    "end_date": <str>,
    "is_canceled": <bool>,
    "household_size_max": <int>
  },
  "credential": {
    "id": <int>,
    "label": <str>,
    "description": <str>,
    "parameters": {
      "lossy_streaming": <bool>,
      "lossless_streaming": <bool>,
      "hires_streaming": <bool>,
      "hires_purchases_streaming": <bool>,
      "mobile_streaming": <bool>,
      "offline_streaming": <bool>,
      "hfp_purchase": <bool>,
      "included_format_group_ids": [<int>],
      "color_scheme": {
        "logo": <str>
      },
      "label": <str>,
      "short_label": <str>,
      "source": <str>
    }
  },
  "last_update": {
    "favorite": <int>,
    "favorite_album": <int>,
    "favorite_artist": <int>,
    "favorite_track": <int>,
    "playlist": <int>,
    "purchase": <int>
  },
  "store_features": {
    "download": <bool>,
    "streaming": <bool>,
    "editorial": <bool>,
    "club": <bool>,
    "wallet": <bool>,
    "weeklyq": <bool>,
    "autoplay": <bool>,
    "inapp_purchase_subscripton": <bool>,
    "opt_in": <bool>,
    "music_import": <bool>
  }
}

get_purchased_item_ids() → dict[str, Any][source]¶

Get the IDs of the current user’s purchased albums and tracks.

User authentication

Requires user authentication via the password flow.

Returns:

purchased_item_idsdict

The current user’s purchased album and track IDs.

Sample response

{
  "albums": {
    "items": [
      {
        "id": <str>
      }
    ],
    "total": <int>
  },
  "tracks": {
    "items": [
      {
        "bought": <bool>,
        "id": <int>
      }
    ],
    "total": <int>
  },
  "user": {
    "id": <int>,
    "login": <str>
  }
}

get_purchases(type: str = 'albums', *, limit: int = None, offset: int = None) → dict[str, Any][source]¶

Get the current user’s purchases.

User authentication

Requires user authentication via the password flow.

Parameters:

typestr, default: "albums"

Media type.

Valid values: "albums" and "tracks".

limitint, keyword-only, optional

The maximum number of albums or tracks to return.

Default: 50.

offsetint, keyword-only, optional

The index of the first album or track to return. Use with limit to get the next page of albums or tracks.

Default: 0.

Returns:

purchasesdict

A dictionary containing Qobuz catalog information for the current user’s purchases.

Sample response

{
  "offset": <int>,
  "limit": <int>,
  "total": <int>,
  "items": <list>
}

get_similar_artists(artist_id: int | str, /, limit: int = None, offset: int = None) → dict[str, Any][source]¶

Get Qobuz catalog information for other artists that are similar to an artist.

Parameters:

artist_idint or str, positional-only

Qobuz artist ID

limitint, keyword-only, optional

The maximum number of artists to return.

Default: 25.

offsetint, keyword-only, optional

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

Default: 0.

Returns:

artistsdict

Qobuz catalog information for similar artists.

Sample response

{
  "artists": {
    "items": [
      {
        "albums_count": <int>,
        "id": <int>,
        "image": {
          "extralarge": <str>,
          "large": <str>,
          "medium": <str>,
          "mega": <str>,
          "small": <str>
        },
        "name": <str>,
        "picture": <str>,
        "slug": <str>
      }
    ],
    "limit": <int>,
    "offset": <int>,
    "total": <int>
  }
}

get_track(track_id: int | str) → dict[str, Any][source]¶

Get Qobuz catalog information for a track.

Parameters:

track_idint or str

Qobuz track ID.

Example: 24393138.

Returns:

trackdict

Qobuz catalog information for the track.

Sample response

{
  "maximum_bit_depth": <int>,
  "copyright": <str>,
  "performers": <str>,
  "audio_info": {
    "replaygain_track_gain": <float>,
    "replaygain_track_peak": <float>
  },
  "performer": {
    "id": <int>,
    "name": <str>
  },
  "album": {
    "maximum_bit_depth": <int>,
    "image": {
      "small": <str>,
      "thumbnail": <str>,
      "large": <str>,
      "back": <str>
    },
    "media_count": <int>,
    "artist": {
      "image": <str>,
      "name": <str>,
      "id": <int>,
      "albums_count": <int>,
      "slug": <str>,
      "picture": <str>
    },
    "artists": [
      {
        "id": <int>,
        "name": <str>,
        "roles": [<str>]
      }
    ],
    "upc": <str>,
    "released_at": <int>,
    "label": {
      "name": <str>,
      "id": <int>,
      "albums_count": <int>,
      "supplier_id": <int>,
      "slug": <str>
    },
    "title": <str>,
    "qobuz_id": <int>,
    "version": <str>,
    "url": <str>,
    "duration": <int>,
    "parental_warning": <bool>,
    "popularity": <int>,
    "tracks_count": <int>,
    "genre": {
      "path": [<int>],
      "color": <str>,
      "name": <str>,
      "id": <int>,
      "slug": <str>
    },
    "maximum_channel_count": <int>,
    "id": <str>,
    "maximum_sampling_rate": <int>,
    "articles": <list>,
    "release_date_original": <str>,
    "release_date_download": <str>,
    "release_date_stream": <str>,
    "purchasable": <bool>,
    "streamable": <bool>,
    "previewable": <bool>,
    "sampleable": <bool>,
    "downloadable": <bool>,
    "displayable": <bool>,
    "purchasable_at": <int>,
    "streamable_at": <int>,
    "hires": <bool>,
    "hires_streamable": <bool>,
    "awards": <list>,
    "description": <str>,
    "description_language": <str>,
    "goodies": <list>,
    "area": null,
    "catchline": <str>,
    "composer": {
      "id": <int>,
      "name": <str>,
      "slug": <str>,
      "albums_count": <int>,
      "picture": <str>,
      "image": <str>
    },
    "created_at": <int>,
    "genres_list": [<str>],
    "period": <str>,
    "copyright": <str>,
    "is_official": <bool>,
    "maximum_technical_specifications": <str>,
    "product_sales_factors_monthly": <int>,
    "product_sales_factors_weekly": <int>,
    "product_sales_factors_yearly": <int>,
    "product_type": <str>,
    "product_url": <str>,
    "recording_information": <str>,
    "relative_url": <str>,
    "release_tags": <list>,
    "release_type": <str>,
    "slug": <str>,
    "subtitle": <str>
  },
  "work": <str>,
  "composer": {
    "id": <int>,
    "name": <str>
  },
  "isrc": <str>,
  "title": <str>,
  "version": <str>,
  "duration": <int>,
  "parental_warning": <bool>,
  "track_number": <int>,
  "maximum_channel_count": <int>,
  "id": <int>,
  "media_number": <int>,
  "maximum_sampling_rate": <int>,
  "articles": <list>,
  "release_date_original": <str>,
  "release_date_download": <str>,
  "release_date_stream": <str>,
  "release_date_purchase": <str>,
  "purchasable": <bool>,
  "streamable": <bool>,
  "previewable": <bool>,
  "sampleable": <bool>,
  "downloadable": <bool>,
  "displayable": <bool>,
  "purchasable_at": <int>,
  "streamable_at": <int>,
  "hires": <bool>,
  "hires_streamable": <bool>
}

get_track_file_url(track_id: int | str, format_id: int | str = 27) → dict[str, Any][source]¶

Get the file URL for a track.

Subscription

Full track playback information and lossless and Hi-Res audio is only available with an active Qobuz subscription.

Parameters:

track_idint or str

Qobuz track ID.

Example: 24393138.

format_idint or str, default: 27

Audio format ID that determines the maximum audio quality.

Valid values:

5 for constant bitrate (320 kbps) MP3.
6 for CD-quality (16-bit, 44.1 kHz) FLAC.
7 for up to 24-bit, 96 kHz Hi-Res FLAC.
27 for up to 24-bit, 192 kHz Hi-Res FLAC.

Returns:

urldict

A dictionary containing the URL and track information, such as the audio format, bit depth, etc.

Sample response

{
  "track_id": <int>,
  "duration": <int>,
  "url": <str>,
  "format_id": <int>,
  "mime_type": <str>,
  "restrictions": [
    {
      "code": <str>
    }
  ],
  "sampling_rate": <int>,
  "bit_depth": <int>
}

get_track_performers(track_id: int | str = None, *, performers: str = None, roles: list[str] | set[str] = None) → dict[str, list][source]¶

Get credits for a track.

Note

This method is provided for convenience and is not a private Qobuz API endpoint.

Parameters:

track_idint or str, optional

Qobuz track ID. Required if performers is not provided.

Example: 24393138.

performersstr, keyword-only, optional

An unformatted string containing the track credits obtained from calling get_track().

roleslist or set, keyword-only, optional

Role filter. The special "Composers" filter will combine the "Composer", "ComposerLyricist", "Lyricist", and "Writer" roles.

Valid values: "MainArtist", "FeaturedArtist", "Producer", "Co-Producer", "Mixer", "Composers" ("Composer", "ComposerLyricist", "Lyricist", "Writer"), "MusicPublisher", etc.

Returns:

creditsdict: A dictionary containing the track contributors, with their roles (in snake case) being the keys.

get_track_recommendations(seed_track_ids: list[dict[str, int]], exclude_track_ids: list[int] = None, *, limit: int = None) → dict[str, Any][source]¶

Get track recommendations based on seed tracks.

User authentication

Requires user authentication via the password flow.

Parameters:

seed_track_idslist

Qobuz IDs of the seed tracks.

Example: [{"qobuz_id": 12345}].

exclude_track_idslist, optional

Qobuz IDs of tracks to exclude from the recommendations.

Example: [12345, 67890].

limitint, keyword-only, optional

The maximum number of recommended tracks to return.

Valid range: 1 to 500.

API default: 50.

Returns:

recommendationsdict

Qobuz catalog information for the recommended tracks.

Sample response

{
  "algorithm": <str>,
  "tracks": {
    "items": [
      {
        "album": {
          "artist": {
            "albums_count": <int>,
            "id": <int>,
            "image": None,
            "name": <str>,
            "picture": None,
            "slug": <str>,
          },
          "displayable": <bool>,
          "downloadable": <bool>,
          "duration": <int>,
          "genre": {
            "id": <int>,
            "name": <str>,
            "path": <list[int]>,
            "slug": <str>
          },
          "hires": <bool>,
          "hires_streamable": <bool>,
          "id": <str>,
          "image": {
            "large": <str>,
            "small": <str>,
            "thumbnail": <str>
          },
          "label": {
            "albums_count": <int>,
            "id": <int>,
            "name": <str>,
            "slug": <str>,
            "supplier_id": <int>
          },
          "maximum_bit_depth": <int>,
          "maximum_channel_count": <int>,
          "maximum_sampling_rate": <float>,
          "media_count": <int>,
          "parental_warning": <bool>,
          "popularity": <int>,
          "previewable": <bool>,
          "purchasable": <bool>,
          "purchasable_at": None,
          "qobuz_id": <int>,
          "release_date_download": <str>,
          "release_date_original": <str>,
          "release_date_stream": <str>,
          "released_at": <int>,
          "sampleable": <bool>,
          "streamable": <bool>,
          "streamable_at": <int>,
          "title": <str>,
          "tracks_count": <int>,
          "upc": <str>,
          "version": <str>
        },
        "audio_info": {
          "replaygain_track_gain": <float>,
          "replaygain_track_peak": <float>
        },
        "composer": {
          "id": <int>,
          "name": <str>
        },
        "copyright": <str>,
        "displayable": <bool>,
        "downloadable": <bool>,
        "duration": <int>,
        "hires": <bool>,
        "hires_streamable": <bool>,
        "id": <int>,
        "isrc": <str>,
        "maximum_bit_depth": <int>,
        "maximum_channel_count": <int>,
        "maximum_sampling_rate": <float>,
        "media_number": <int>,
        "parental_warning": <bool>,
        "performer": {
          "id": <int>,
          "name": <str>
        },
        "performers": <str>,
        "previewable": <bool>,
        "purchasable": <bool>,
        "purchasable_at": <int>,
        "sampleable": <bool>,
        "streamable": <bool>,
        "streamable_at": <int>,
        "title": <str>,
        "track_number": <int>,
        "version": <str>,
        "work": None
      }
    ],
    "limit": <int>
  }
}

get_track_stream(track_id: int | str, *, format_id: int | str = 27) → tuple[bytes, str][source]¶

Get the audio stream data for a track.

Subscription

Full track playback information and lossless and Hi-Res audio is only available with an active Qobuz subscription.

Note

This method is provided for convenience and is not a private Qobuz API endpoint.

Parameters:

track_idint or str

Qobuz track ID.

Example: 24393138.

format_idint, default: 27

Audio format ID that determines the maximum audio quality.

Valid values:

5 for constant bitrate (320 kbps) MP3.
6 for CD-quality (16-bit, 44.1 kHz) FLAC.
7 for up to 24-bit, 96 kHz Hi-Res FLAC.
27 for up to 24-bit, 192 kHz Hi-Res FLAC.

Returns:

streambytes: Audio stream data.
mime_typestr: Audio stream MIME type.

get_tracks(track_ids: list[int | str]) → dict[str, Any][source]¶

Get Qobuz catalog information for multiple tracks.

Parameters:

track_idslist of int or str

List of Qobuz track IDs.

Example: [24393138, 24393139].

Returns:

tracksdict

Qobuz catalog information for the tracks.

Sample response

{
  "items": {
    "album": {
      "area": None,
      "articles": [],
      "artist": {
        "albums_count": <int>,
        "id": <int>,
        "image": None,
        "name": <str>,
        "picture": None,
        "slug": <str>
      },
      "artists": [
        {
          "id": <int>,
          "name": <str>,
          "roles": <list[str]>
        }
      ],
      "awards": [
        {
          "award_id": <str>,
          "award_slug": <str>,
          "awarded_at": <int>,
          "name": <str>,
          "publication_id": <str>,
          "publication_name": <str>,
          "publication_slug": <str>,
          "slug": <str>
        }
      ],
      "catchline": <str>,
      "composer": {
        "albums_count": <int>,
        "id": <int>,
        "image": None,
        "name": <str>,
        "picture": None,
        "slug": <str>
      },
      "copyright": <str>,
      "created_at": <int>,
      "description": <str>,
      "description_language": <str>,
      "displayable": <bool>,
      "downloadable": <bool>,
      "duration": <int>,
      "genre": {
        "color": <int>,
        "id": <int>,
        "name": <int>,
        "path": <list[int]>,
        "slug": <str>
      },
      "genres_list": <list[str]>,
      "goodies": [],
      "hires": <bool>,
      "hires_streamable": <bool>,
      "id": <str>,
      "image": {
        "back": None,
        "large": <str>,
        "small": <str>,
        "thumbnail": <str>
      },
      "is_official": <bool>,
      "label": {
        "albums_count": <int>,
        "id": <int>,
        "name": <str>,
        "slug": <str>,
        "supplier_id": <int>
      },
      "maximum_bit_depth": <int>,
      "maximum_channel_count": <int>,
      "maximum_sampling_rate": <int>,
      "maximum_technical_specifications": <str>,
      "media_count": <int>,
      "parental_warning": <bool>,
      "period": None,
      "popularity": <int>,
      "previewable": <bool>,
      "product_sales_factors_monthly": <int>,
      "product_sales_factors_weekly": <int>,
      "product_sales_factors_yearly": <int>,
      "product_type": <str>,
      "product_url": <str>,
      "purchasable": <bool>,
      "purchasable_at": <int>,
      "qobuz_id": <int>,
      "recording_information": <str>,
      "relative_url": <str>,
      "release_date_download": <str>,
      "release_date_original": <str>,
      "release_date_stream": <str>,
      "release_tags": <list[str]>,
      "release_type": <str>,
      "released_at": <int>,
      "sampleable": <bool>,
      "slug": <str>,
      "streamable": <bool>,
      "streamable_at": <int>,
      "subtitle": <str>,
      "title": <str>,
      "tracks_count": <int>,
      "upc": <str>,
      "url": <str>,
      "version": <str>
    },
    "articles": [],
    "audio_info": {
      "replaygain_track_gain": <float>,
      "replaygain_track_peak": <float>
    },
    "composer": {
      "id": <int>,
      "name": <str>
    },
    "copyright": <str>,
    "created_at": <int>,
    "displayable": <bool>,
    "downloadable": <bool>,
    "duration": <int>,
    "hires": <bool>,
    "hires_streamable": <bool>,
    "id": <int>,
    "indexed_at": <int>,
    "isrc": <str>,
    "maximum_bit_depth": <int>,
    "maximum_channel_count": <int>,
    "maximum_sampling_rate": <int>,
    "media_number": <int>,
    "parental_warning": <bool>,
    "performer": {
      "id": <int>,
      "name": <str>
    },
    "performers": <str>,
    "previewable": <bool>,
    "purchasable": <bool>,
    "purchasable_at": <int>,
    "release_date_download": <str>,
    "release_date_original": <str>,
    "release_date_purchase": <str>,
    "release_date_stream": <str>,
    "sampleable":<bool>,
    "streamable": <bool>,
    "streamable_at": <int>,
    "title": <str>,
    "track_number": <int>,
    "version": <str>,
    "work": None
  },
  "total": <int>
}

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

Get the current user’s custom and favorite playlists.

User authentication

Requires user authentication via the password flow.

Parameters:

limitint, keyword-only, optional

The maximum number of playlists to return.

Default: 500.

offsetint, keyword-only, optional

The index of the first playlist to return. Use with limit to get the next page of playlists.

Default: 0.

Returns:

playlistsdict

Qobuz catalog information for the current user’s custom and favorite playlists.

Sample response

{
  "offset": <int>,
  "limit": <int>,
  "total": <int>,
  "items": [
    {
      "image_rectangle_mini": [<str>],
      "is_published": <bool>,
      "featured_artists": <list>,
      "description": <str>,
      "created_at": <int>,
      "timestamp_position": <int>,
      "images300": [<str>],
      "duration": <int>,
      "updated_at": <int>,
      "published_to": <int>,
      "genres": <list>,
      "image_rectangle": [<str>],
      "id": <int>,
      "slug": <str>,
      "owner": {
        "id": <int>,
        "name": <str>
      },
      "users_count": <int>,
      "images150": [<str>],
      "images": [<str>],
      "is_collaborative": <bool>.
      "stores": [<str>],
      "tracks_count": <int>,
      "public_at": <int>,
      "name": "Welcome to Qobuz",
      "is_public": <bool>,
      "published_from": <int>,
      "is_featured": <bool>,
      "position": <int>
    }
  ]
}

move_playlist_tracks(playlist_id: int | str, playlist_track_ids: int | str | list[int | str], insert_before: int) → dict[str, Any][source]¶

Move tracks in a user playlist.

User authentication

Requires user authentication via the password flow.

Parameters:

playlist_idint or str

Qobuz user playlist ID.

Example: 17737508.

playlist_track_idsint, str, or list

Qobuz playlist track ID(s).

Note

Playlist track IDs are not the same as track IDs. To get playlist track IDs, use get_playlist().

insert_beforeint

Position to which to move the tracks specified in track_ids.

Returns:

playliststr

Qobuz catalog information for the updated playlist.

Sample response

{
  "id": <int>,
  "name": <str>,
  "description": <str>,
  "tracks_count": <int>,
  "users_count": <int>,
  "duration": <int>,
  "public_at": <int>,
  "created_at": <int>,
  "updated_at": <int>,
  "is_public": <bool>,
  "is_collaborative": <bool>,
  "owner": {
    "id": <int>,
    "name": <str>
  }
}

search(query: str, type: str = 'catalog', *, limit: int = 10, offset: int = 0) → dict[str, Any][source]¶

Search Qobuz for media and performers.

Parameters:

querystr

Search query.

Tip

Searches can be narrowed using tags, such as #ByMainArtist, #ByComposer, #ByPerformer, #ByReleaseName, #ByLabel, "#NewRelease", and #HiRes.

Use strict matching instead of fuzzy search by wrapping the keyword string in double quotes.

Example: "Galantis" #ByMainArtist #HiRes.

typestr, keyword-only, optional

Resource type.

Valid values: "album", "artist", "catalog", "playlist", "story", "track".

limitint, keyword-only, default: 10

Maximum number of results to return.

offsetint, keyword-only, default: 0

Index of the first result to return. Use with limit to get the next page of search results.

Returns:

resultsdict

Search results.

Sample response

{
  "query": <str>,
  "albums": {
    "limit": <int>,
    "offset": <int>,
    "total": <int>,
    "items": [
      {
        "maximum_bit_depth": <int>,
        "image": {
          "small": <str>,
          "thumbnail": <str>,
          "large": <str>,
          "back": <str>,
        },
        "media_count": <int>,
        "artist": {
          "image": <str>,
          "name": <str>,
          "id": <int>,
          "albums_count": <int>,
          "slug": <str>,
          "picture": <str>
        },
        "artists": [
          {
            "id": <int>,
            "name": <str>,
            "roles": [<str>]
          }
        ],
        "upc": <str>,
        "released_at": <int>,
        "label": {
          "name": <str>,
          "id": <int>,
          "albums_count": <int>,
          "supplier_id": <int>,
          "slug": <str>
        },
        "title": <str>,
        "qobuz_id": <int>,
        "version": <str>,
        "url": <str>,
        "duration": <int>,
        "parental_warning": <bool>,
        "popularity": <int>,
        "tracks_count": <int>,
        "genre": {
          "path": [<int>],
          "color": <str>,
          "name": <str>,
          "id": <int>,
          "slug": <str>
        },
        "maximum_channel_count": <int>,
        "id": <str>,
        "maximum_sampling_rate": <int>,
        "articles": <list>,
        "release_date_original": <str>,
        "release_date_download": <str>,
        "release_date_stream": <str>,
        "purchasable": <bool>,
        "streamable": <bool>,
        "previewable": <bool>,
        "sampleable": <bool>,
        "downloadable": <bool>,
        "displayable": <bool>,
        "purchasable_at": <int>,
        "streamable_at": <int>,
        "hires": <bool>,
        "hires_streamable": <bool>
      }
    ]
  },
  "tracks": {
    "limit": <int>,
    "offset": <int>,
    "total": <int>,
    "items": [
      {
        "maximum_bit_depth": <int>,
        "copyright": <str>,
        "performers": <str>,
        "audio_info": {
          "replaygain_track_peak": <float>,
          "replaygain_track_gain": <float>
        },
        "performer": {
          "name": <str>,
          "id": <int>
        },
        "album": {
          "image": {
            "small": <str>,
            "thumbnail": <str>,
            "large": <str>
          },
          "maximum_bit_depth": <int>,
          "media_count": <int>,
          "artist": {
            "image": <str>,
            "name": <str>,
            "id": <int>,
            "albums_count": <int>,
            "slug":<str>,
            "picture": <str>
          },
          "upc": <str>,
          "released_at": <int>,
          "label": {
            "name": <str>,
            "id": <int>,
            "albums_count": <int>,
            "supplier_id": <int>,
            "slug": <str>
          },
          "title": <str>,
          "qobuz_id": <int>,
          "version": <str>,
          "duration": <int>,
          "parental_warning": <bool>,
          "tracks_count": <int>,
          "popularity": <int>,
          "genre": {
            "path": [<int>],
            "color": <str>,
            "name": <str>,
            "id": <int>,
            "slug": <str>
          },
          "maximum_channel_count": <int>,
          "id": <str>,
          "maximum_sampling_rate": <int>,
          "previewable": <bool>,
          "sampleable": <bool>,
          "displayable": <bool>,
          "streamable": <bool>,
          "streamable_at": <int>,
          "downloadable": <bool>,
          "purchasable_at": <int>,
          "purchasable": <bool>,
          "release_date_original": <str>,
          "release_date_download": <str>,
          "release_date_stream": <str>,
          "release_date_purchase": <str>,
          "hires": <bool>,
          "hires_streamable": <bool>
        },
        "work": <str>,
        "composer": {
          "name": <str>,
          "id": <int>
        },
        "isrc": <str>,
        "title": <str>,
        "version": <str>,
        "duration": <int>,
        "parental_warning": <bool>,
        "track_number": <int>,
        "maximum_channel_count": <int>,
        "id": <int>,
        "media_number": <int>,
        "maximum_sampling_rate": <int>,
        "release_date_original": <str>,
        "release_date_download": <str>,
        "release_date_stream": <str>,
        "release_date_purchase": <str>,
        "purchasable": <bool>,
        "streamable": <bool>,
        "previewable": <bool>,
        "sampleable": <bool>,
        "downloadable": <bool>,
        "displayable": <bool>,
        "purchasable_at": <int>,
        "streamable_at": <int>,
        "hires": <bool>,
        "hires_streamable": <bool>
      }
    ]
  },
  "artists": {
    "limit": <int>,
    "offset": <int>,
    "total": <int>,
    "items": [
      {
        "picture": <str>,
        "image": {
          "small": <str>,
          "medium": <str>,
          "large": <str>,
          "extralarge": <str>,
          "mega": <str>
        },
        "name": <str>,
        "slug": <str>,
        "albums_count": <int>,
        "id": <int>
      }
    ]
  },
  "playlists": {
    "limit": <int>,
    "offset": <int>,
    "total": <int>,
    "items": [
      {
        "image_rectangle_mini": [<str>],
        "is_published": <bool>,
        "featured_artists": <list>,
        "description": <str>,
        "created_at": <int>,
        "timestamp_position": <int>,
        "images300": [<str>],
        "duration": <int>,
        "updated_at": <int>,
        "published_to": <int>,
        "genres": <list>,
        "image_rectangle": [<str>],
        "id": <int>,
        "slug": <str>,
        "owner": {
          "id": <int>,
          "name": <str>
        },
        "users_count": <int>,
        "images150": [<str>],
        "images": [<str>],
        "is_collaborative": <bool>,
        "stores": [<str>],
        "tags": [
          {
            "featured_tag_id": <str>,
            "name_json": <str>,
            "slug": <str>,
            "color": <str>,
            "genre_tag": <str>,
            "is_discover": <bool>
          }
        ],
        "tracks_count": <int>,
        "public_at": <int>,
        "name": <str>,
        "is_public": <bool>,
        "published_from": <int>,
        "is_featured": <bool>
      }
    ]
  },
  "focus": {
    "limit": <int>,
    "offset": <int>,
    "total": <int>,
    "items": [
      {
        "image": <str>,
        "name_superbloc": <str>,
        "accroche": <str>,
        "id": <str>,
        "title": <str>,
        "genre_ids": [<str>],
        "author": <str>,
        "date": <str>
      }
    ]
  },
  "articles": {
    "limit": <int>,
    "offset": <int>,
    "total": <int>,
    "items": [
      {
        "image": <str>,
        "thumbnail": <str>,
        "root_category": <int>,
        "author": <str>,
        "abstract": <str>,
        "source": <str>,
        "title": <str>,
        "type": <str>,
        "url": <str>,
        "image_original": <str>,
        "category_id": <int>,
        "source_image": <str>,
        "id": <int>,
        "published_at": <int>,
        "category": <str>
      }
    ]
  },
  "stories": {
    "limit": <int>,
    "offset": <int>,
    "total": <int>,
    "items": [
      {
        "id": <str>,
        "section_slugs": [<str>],
        "title": <str>,
        "description_short": <str>,
        "authors": [
          {
            "id": <str>,
            "name": <str>,
            "slug": <str>
          }
        ],
        "image": <str>,
        "display_date": <int>
      }
    ]
  }
}

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

Search for albums in the Qobuz catalog.

Parameters:

querystr

Search query.

limitint, keyword-only, optional

The maximum number of albums to return.

Default: 50.

offsetint, keyword-only, optional

The index of the first album to return. Use with limit to get the next page of albums.

Default: 0.

Returns:

albumsdict

Qobuz catalog information for the albums matching the search query.

Sample response

{
  "albums": {
    "items": [
      {
        "articles": [],
        "artist": {
          "albums_count": <int>,
          "id": <int>,
          "image": None,
          "name": <str>,
          "picture": None,
          "slug": <str>
        },
        "artists": [
          {
            "id": <int>,
            "name": <str>,
            "roles": <list[str]>
          }
        ],
        "displayable": <bool>,
        "downloadable": <bool>,
        "duration": <int>,
        "genre": {
          "color": <str>,
          "id": <int>,
          "name": <str>,
          "path": <list[int]>,
          "slug": <str>
        },
        "hires": <bool>,
        "hires_streamable": <bool>,
        "id": <str>,
        "image": {
          "back": None,
          "large": <str>,
          "small": <str>,
          "thumbnail": <str>
        },
        "label": {
          "albums_count": <int>,
          "id": <int>,
          "name": <str>,
          "slug": <str>,
          "supplier_id": <int>
        },
        "maximum_bit_depth": <int>,
        "maximum_channel_count": <int>,
        "maximum_sampling_rate": <float>,
        "media_count": <int>,
        "parental_warning": <bool>,
        "popularity": <int>,
        "previewable": <bool>,
        "purchasable": <bool>,
        "purchasable_at": <int>,
        "qobuz_id": <int>,
        "release_date_download": <str>,
        "release_date_original": <str>,
        "release_date_stream": <str>,
        "released_at": <int>,
        "sampleable": <bool>,
        "slug": <str>,
        "streamable": <bool>,
        "streamable_at": <int>,
        "title": <str>,
        "tracks_count": <int>,
        "upc": <str>,
        "url": <str>,
        "version": <str>
      }
    ],
    "limit": <int>,
    "offset": <int>,
    "total": <int>
  },
  "query": <str>
}

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

Search for artists in the Qobuz catalog.

Parameters:

querystr

Search query.

limitint, keyword-only, optional

The maximum number of artists to return.

Default: 25.

offsetint, keyword-only, optional

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

Default: 0.

Returns:

artistsdict

Qobuz catalog information for the artists matching the search query.

Sample response

{
  "artists": {
    "items": [
      {
        "albums_count": <int>,
        "id": <int>,
        "image": {
          "extralarge": <str>,
          "large": <str>,
          "medium": <str>,
          "mega": <str>,
          "small": <str>
        },
        "name": <str>,
        "picture": <str>,
        "slug": <str>
      }
    ],
    "limit": <int>,
    "offset": <int>,
    "total": <int>
  },
  "query": <str>
}

search_most_popular(query: str, offset: int = None) → dict[str, Any][source]¶

Get Qobuz catalog information for the 30 most popular albums, artists, and tracks that match a keyword string.

Parameters:

querystr, positional-only

Search query.

Tip

Searches can be narrowed using tags, such as #ByMainArtist, #ByComposer, #ByPerformer, #ByReleaseName, #ByLabel, #NewRelease, and #HiRes.

Use strict matching instead of fuzzy search by wrapping the keyword string in double quotes.

Example: "Galantis" #ByMainArtist #HiRes.

offsetint, keyword-only, optional

Index of the first item to return.

Minimum value: 0.

API default: 0.

Returns:

itemsdict

Qobuz catalog information for the most popular items.

Sample

{
  "most_popular": {
    "items": [
      {
        "content": {
          "articles": [],
          "artist": {
            "albums_count": <int>,
            "id": <int>,
            "image": None,
            "name": <str>,
            "picture": None,
            "slug": <str>,
          },
          "artists": [
            {
              "id": <int>,
              "name": <str>,
              "roles": <list[str]>
            }
          ],
          "displayable": <bool>,
          "downloadable": <bool>,
          "duration": <int>,
          "genre": {
            "color": <str>,
            "id": <int>,
            "name": <str>,
            "path": <list[int]>,
            "slug": <str>
          },
          "hires": <bool>,
          "hires_streamable": <bool>,
          "id": <str>,
          "image": {
            "back": None,
            "large": <str>,
            "small": <str>,
            "thumbnail": <str>
          },
          "label": {
            "albums_count": <int>,
            "id": <int>,
            "name": <str>,
            "slug": <str>,
            "supplier_id": <int>
          },
          "maximum_bit_depth": <int>,
          "maximum_channel_count": <int>,
          "maximum_sampling_rate": <float>,
          "media_count": <int>,
          "parental_warning": <bool>,
          "popularity": <int>,
          "previewable": <bool>,
          "purchasable": <bool>,
          "purchasable_at": <int>,
          "qobuz_id": <int>,
          "release_date_download": <str>,
          "release_date_original": <str>,
          "release_date_stream": <str>,
          "released_at": <int>,
          "sampleable": <bool>,
          "slug": <str>,
          "streamable": <bool>,
          "streamable_at": <int>,
          "title": <str>,
          "tracks_count": <int>,
          "type": <str>,
          "upc": <str>,
          "url": <str>,
          "version": <str>
        },
        "type": "albums"
      },
      {
        "content": {
          "albums_count": <int>,
          "id": <int>,
          "image": {
            "extralarge": <str>,
            "large": <str>,
            "medium": <str>,
            "mega": <str>,
            "small": <str>
          },
          "name": <str>,
          "picture": <str>,
          "slug": <str>,
          "type": "artists"
        },
        "type": "artists"
      },
      {
        "content": {
          "album": {
            "artist": {
              "albums_count": <int>,
              "id": <int>,
              "image": None,
              "name": <str>,
              "picture": None,
              "slug": <str>
            },
            "displayable": <bool>,
            "downloadable": <bool>,
            "duration": <int>,
            "genre": {
              "id": <int>,
              "name": <str>,
              "path": <list[int]>,
              "slug": <str>
            },
            "hires": <bool>,
            "hires_streamable": <bool>,
            "id": <str>,
            "image": {
              "large": <str>,
              "small": <str>,
              "thumbnail": <str>
            },
            "label": {
              "albums_count": <int>,
              "id": <int>,
              "name": <str>,
              "slug": <str>,
              "supplier_id": <int>
            },
            "maximum_bit_depth": <int>,
            "maximum_channel_count": <int>,
            "maximum_sampling_rate": <float>,
            "maximum_technical_specifications": <str>,
            "media_count": <int>,
            "parental_warning": <bool>,
            "previewable": <bool>,
            "purchasable": <bool>,
            "purchasable_at": None,
            "qobuz_id": <int>,
            "release_date_download": <str>,
            "release_date_original": <str>,
            "release_date_purchase": <str>,
            "release_date_stream": <str>,
            "released_at": <int>,
            "sampleable": <bool>,
            "streamable": <bool>,
            "streamable_at": <int>,
            "title": <str>,
            "tracks_count": <int>,
            "upc": <str>,
            "version": <str>
          },
          "article_ids": dict[str, int],
          "articles": [
            {
              "currency": <str>,
              "description": <str>,
              "id": <int>,
              "label": <str>,
              "price": <float>,
              "type": <str>,
              "url": <str>
            }
          ],
          "audio_info": {
            "replaygain_track_gain": <float>,
            "replaygain_track_peak": <float>
          },
          "composer": {
            "id": <int>,
            "name": <str>
          },
          "copyright": <str>,
          "displayable": <bool>,
          "downloadable": <bool>,
          "duration": <int>,
          "hires": <bool>,
          "hires_streamable": <bool>,
          "id": <int>,
          "isrc": <str>,
          "maximum_bit_depth": <int>,
          "maximum_channel_count": <int>,
          "maximum_sampling_rate": <float>,
          "maximum_technical_specifications": <str>,
          "media_number": <int>,
          "parental_warning": <bool>,
          "performer": {
            "id": <int>,
            "name": <str>
          },
          "performers": <str>,
          "previewable": <bool>,
          "purchasable": <bool>,
          "purchasable_at": <int>,
          "release_date_download": <str>,
          "release_date_original": <str>,
          "release_date_purchase": <str>,
          "release_date_stream": <str>,
          "sampleable": <bool>,
          "streamable": <bool>,
          "streamable_at": <int>,
          "title": <str>,
          "track_number": <int>,
          "type": "tracks",
          "version": <str>,
          "work": None
        },
        "type": "tracks"
      }
    ],
    "limit": <int>,
    "offset": <int>,
    "total": <int>
  },
  "query": <str>
}

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

Search for playlists in the Qobuz catalog.

Parameters:

querystr, positional-only

Search query.

Tip

Searches can be narrowed using tags, such as #ByMainArtist, #ByComposer, #ByPerformer, #ByReleaseName, #ByLabel, #NewRelease, and #HiRes.

Use strict matching instead of fuzzy search by wrapping the keyword string in double quotes.

Example: "Galantis" #ByMainArtist #HiRes.

limitint, keyword-only, optional

Maximum number of playlists to return.

Valid range: 1 to 500.

API default: 50.

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

Qobuz catalog information for the matching playlists.

Sample

{
  "playlists": {
    "items": [
      {
        "created_at": <int>,
        "description": <str>,
        "duration": <int>,
        "featured_artists": [
          {
            "albums_count": <int>,
            "id": <int>,
            "image": None,
            "name": <str>,
            "picture": None,
            "slug": <str>
          }
        ],
        "genres": [
          {
            "color": <str>,
            "id": <int>,
            "name": <str>,
            "path": <list[int]>,
            "percent": <int>,
            "slug": <str>
          }
        ],
        "id": <int>,
        "image_rectangle": <list[str]>,
        "image_rectangle_mini": <list[str]>,
        "images": <list[str]>,
        "images150": <list[str]>,
        "images300": <list[str]>,
        "indexed_at": <int>,
        "is_collaborative": <bool>,
        "is_featured": <bool>,
        "is_public": <bool>,
        "is_published": <bool>,
        "name": <str>,
        "owner": {
          "id": <int>,
          "name": <str>
        },
        "public_at": <int>,
        "published_from": <int>,
        "published_to": <int>,
        "slug": <str>,
        "stores": <list[str]>,
        "tags": [
          {
            "color": <str>,
            "featured_tag_id": <str>,
            "genre_tag": {
              "genre_id": <str>,
              "name": <str>
            },
            "is_discover": <bool>,
            "name_json": <str>,
            "slug": <str>
          }
        ],
        "timestamp_position": <int>,
        "tracks_count": <int>,
        "updated_at": <int>,
        "users_count": <int>
      }
    ],
    "limit": <int>,
    "offset": <int>,
    "total": <int>
  },
  "query": <str>
}

search_stories(query: str, /, *, limit: int = None, offset: int = None) → dict[str, Any][source]¶

Search for stories in the Qobuz catalog.

Parameters:

querystr, positional-only

Search query.

Tip

Searches can be narrowed using tags, such as #ByMainArtist, #ByComposer, #ByPerformer, #ByReleaseName, #ByLabel, #NewRelease, and #HiRes.

Use strict matching instead of fuzzy search by wrapping the keyword string in double quotes.

Example: "Galantis" #ByMainArtist #HiRes.

limitint, keyword-only, optional

Maximum number of stories to return.

Valid range: 1 to 500.

API default: 50.

offsetint, keyword-only, optional

Index of the first story to return. Use with limit to get the next batch of stories.

Minimum value: 0.

API default: 0.

Returns:

storiesdict

Qobuz catalog information for the matching stories.

Sample response

{
  "query": <str>,
  "stories": {
    "items": [
      {
        "authors": [
          {
            "id": <str>,
            "name": <str>,
            "slug": <str>
          }
        ],
        "description_short": <str>,
        "display_date": <int>,
        "id": <str>,
        "image": <str>,
        "images": [
          {
            "format": <str>,
            "url": <str>
          }
        ],
        "section_slugs": <list[str]>,
        "title": <str>
      }
    ],
    "limit": <int>,
    "offset": <int>,
    "total": <int>
  }
}

search_tracks(query: str, limit: int = None, offset: int = None) → dict[str, Any][source]¶

Search for tracks in the Qobuz catalog.

Parameters:

querystr, positional-only

Search query.

Tip

Searches can be narrowed using tags, such as #ByMainArtist, #ByComposer, #ByPerformer, #ByReleaseName, #ByLabel, #NewRelease, and #HiRes.

Use strict matching instead of fuzzy search by wrapping the keyword string in double quotes.

Example: "Galantis" #ByMainArtist #HiRes.

limitint, keyword-only, optional

Maximum number of tracks to return.

Valid range: 1 to 500.

API default: 50.

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

Qobuz catalog information for the matching tracks.

Sample response

{
  "query": <str>,
  "tracks": {
    "items": [
      {
        "album": {
          "artist": {
            "albums_count": <int>,
            "id": <int>,
            "image": None,
            "name": <str>,
            "picture": None,
            "slug": <str>
          },
          "displayable": <bool>,
          "downloadable": <bool>,
          "duration": <int>,
          "genre": {
            "color": <int>,
            "id": <int>,
            "name": <int>,
            "path": <list[int]>,
            "slug": <str>
          },
          "hires": <bool>,
          "hires_streamable": <bool>,
          "id": <str>,
          "image": {
            "large": <str>,
            "small": <str>,
            "thumbnail": <str>
          },
          "label": {
            "albums_count": <int>,
            "id": <int>,
            "name": <str>,
            "slug": <str>,
            "supplier_id": <int>
          },
          "maximum_bit_depth": <int>,
          "maximum_channel_count": <int>,
          "maximum_sampling_rate": <int>,
          "maximum_technical_specifications": <str>,
          "media_count": <int>,
          "parental_warning": <bool>,
          "previewable": <bool>,
          "purchasable": <bool>,
          "purchasable_at": <int>,
          "qobuz_id": <int>,
          "release_date_download": <str>,
          "release_date_original": <str>,
          "release_date_purchase": <str>,
          "release_date_stream": <str>,
          "released_at": <int>,
          "sampleable": <bool>,
          "streamable": <bool>,
          "streamable_at": <int>,
          "title": <str>,
          "tracks_count": <int>,
          "upc": <str>,
          "version": <str>
        },
        "audio_info": {
          "replaygain_track_gain": <float>,
          "replaygain_track_peak": <float>
        },
        "copyright": <str>,
        "displayable": <bool>,
        "downloadable": <bool>,
        "duration": <int>,
        "hires": <bool>,
        "hires_streamable": <bool>,
        "id": <int>,
        "isrc": <str>,
        "maximum_bit_depth": <int>,
        "maximum_channel_count": <int>,
        "maximum_sampling_rate": <float>,
        "maximum_technical_specifications": <str>,
        "media_number": <int>,
        "parental_warning": <bool>,
        "performer": {
          "id": <int>,
          "name": <str>
        },
        "performers": <str>,
        "previewable": <bool>,
        "purchasable": <bool>,
        "purchasable_at": <int>,
        "release_date_download": <str>,
        "release_date_original": <str>,
        "release_date_purchase": <str>,
        "release_date_stream": <str>,
        "sampleable": <bool>,
        "streamable": <bool>,
        "streamable_at": <int>,
        "title": <str>,
        "track_number": <int>,
        "version": <str>,
        "work": None
      }
    ],
    "limit": <int>,
    "offset": <int>,
    "total": <int>
  }
}

set_auth_token(auth_token: str = None, *, email: str = None, password: str = None) → None[source]¶

Set the private Qobuz API user authentication token.

Parameters:

auth_tokenstr, optional: User authentication token.
emailstr, keyword-only, optional: Account email address.
passwordstr, keyword-only, optional: Account password.

set_flow(flow: str, *, app_id: str = None, app_secret: str = None, auth_token: str = None, browser: bool = False, save: bool = True) → None[source]¶

Set the authorization flow.

Parameters:

flowstr, keyword-only, optional

Authorization flow.

Valid values:

"password" for the password flow.
None for no authentication.

app_idstr, keyword-only, optional

App ID. Required if an user authentication token is provided in auth_token.

app_secretstr, keyword-only, optional

App secret. Required if an user authentication token is provided in auth_token.

auth_tokenstr, keyword-only, optional

User authentication token.

browserbool, keyword-only, default: False

Determines whether a web browser is opened with the Qobuz login page using the Playwright framework by Microsoft to complete the password flow.

savebool, keyword-only, default: True

Determines whether to save the newly obtained access tokens and their associated properties to the Minim configuration file.

toggle_favorited(type: str, item_id: int | str) → dict[str, bool][source]¶

Toggle the favorited status of an item.

User authentication

Requires user authentication via the password flow.

Parameters:

typestr

Type of item.

Valid values: "album", "artist", "article", "award", "label", "track".

item_idint or str

Qobuz ID of the item.

Returns:

saveddict[str, bool]

Whether the current user has the specified item in their favorites.

Sample response: {"status": <bool>}.

Unfavorite albums, artists, and/or tracks.

User authentication

Requires user authentication via the password flow.