PrivateCatalogAPI

class minim.api.qobuz.PrivateCatalogAPI(client: APIClient, /)

Bases: PrivateQobuzResourceAPI

Catalog API endpoints for the private Qobuz API.

Important

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

Parameters:

clientminim.api._shared.APIClient

API client instance used to make HTTP requests.

Methods

get_featured	Get Qobuz catalog information for featured albums, artists, articles, and/or playlists.
get_num_search_matches	Get the number of Qobuz catalog search results for a query.
search	Search for albums, artists, playlists, stories, and/or tracks in the Qobuz catalog.

get_featured(item_type: str | None = None, /, genre_ids: int | str | Collection[int | str] | None = None, *, limit: int | None = None, offset: int | None = None) → dict[str, Any]

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

Parameters:

item_typestr; positional-only; 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 Collection[int | str]; 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

Maximum number of items to return per item type.

Valid range: 1 to 500.

API default: 25.

offsetint; keyword-only; optional

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

Minimum value: 0.

API default: 0.

Returns:

itemsdict[str, Any]

Page of Qobuz metadata 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_num_search_matches(query: str, /) → dict[str, dict[str, int]]

Get the number of Qobuz catalog search results for a query.

Parameters:

querystr; positional-only

Search query.

Returns:

num_matchesdict[str, dict[str, int]]

Number of search results for the query.

Sample response

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

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

Search for albums, artists, playlists, stories, and/or 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 items to return.

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.

Minimum value: 0.

API default: 0.

Returns:

itemsdict[str, Any]

Page of Qobuz metadata for the matching catalog 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>
  },
  "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>,
  "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>
  },
  "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>
  }
}