qobuz_api_rust/api/content/
catalog.rs

1use crate::{
2    api::service::QobuzApiService,
3    errors::QobuzApiError::{self},
4    models::SearchResult,
5};
6
7/// Provides functionality for interacting with the Qobuz catalog API.
8///
9/// This module contains methods for searching the Qobuz music catalog, allowing
10/// users to find albums, artists, tracks, and other content based on various criteria.
11impl QobuzApiService {
12    /// Searches the Qobuz catalog for content matching the specified query.
13    ///
14    /// This method allows you to search across the entire Qobuz catalog or filter
15    /// results by a specific content type. The search is performed using the Qobuz API
16    /// and returns a [`SearchResult`] containing the matching items.
17    ///
18    /// # Arguments
19    ///
20    /// * `query` - The search query string. This can be an artist name, album title,
21    ///   track title, or any other text to search for in the catalog.
22    /// * `limit` - The maximum number of results to return. Defaults to 50 if not specified.
23    ///   The API may return fewer results than requested depending on the search criteria.
24    /// * `offset` - The offset of the first result to return, used for pagination.
25    ///   Defaults to 0 if not specified, which returns results starting from the first match.
26    /// * `type_param` - Optional parameter to limit results to a specific content type.
27    ///   Valid values include "albums", "artists", "tracks", "playlists", "labels", etc.
28    ///   If not specified, results from all content types will be returned.
29    /// * `with_auth` - Whether to execute the search with the user's authentication token.
30    ///   This parameter is currently unused in the implementation but is reserved for
31    ///   future use to enable authenticated searches that may return personalized results.
32    ///
33    /// # Examples
34    ///
35    /// ```
36    /// # use qobuz_api_rust::{QobuzApiService, QobuzApiError};
37    /// # async fn example() -> Result<(), QobuzApiError> {
38    /// let api = QobuzApiService::new().await?;
39    ///
40    /// // Search for "Billie Eilish" across all content types
41    /// let results = api.search_catalog("Billie Eilish", None, None, None, None).await?;
42    ///
43    /// // Search for only albums by "Billie Eilish", limited to 10 results
44    /// let album_results = api.search_catalog("Billie Eilish", Some(10), None, Some("albums"), None).await?;
45    /// # Ok(())
46    /// # }
47    /// ```
48    ///
49    /// # Returns
50    ///
51    /// * `Ok(SearchResult)` - Contains the search results with matching albums, artists,
52    ///   tracks, and other content based on the query. The structure includes separate
53    ///   sections for each content type that had matching results.
54    /// * `Err(QobuzApiError)` - If the API request fails due to network issues,
55    ///   authentication problems, invalid parameters, or other API-related errors.
56    ///
57    /// # Errors
58    ///
59    /// This function will return an error in the following cases:
60    ///
61    /// * Network connectivity issues preventing the API request
62    /// * Invalid API credentials (app ID or app secret)
63    /// * Invalid parameters passed to the API
64    /// * API rate limiting
65    /// * Server-side errors from the Qobuz API
66    /// * JSON parsing errors when processing the API response
67    ///
68    /// # API Endpoint
69    ///
70    /// This method calls the `/catalog/search` endpoint of the Qobuz API.
71    pub async fn search_catalog(
72        &self,
73        query: &str,
74        limit: Option<i32>,
75        offset: Option<i32>,
76        type_param: Option<&str>,
77        with_auth: Option<bool>,
78    ) -> Result<SearchResult, QobuzApiError> {
79        let mut params = vec![
80            ("query".to_string(), query.to_string()),
81            ("limit".to_string(), limit.unwrap_or(50).to_string()),
82            ("offset".to_string(), offset.unwrap_or(0).to_string()),
83        ];
84
85        if let Some(type_val) = type_param {
86            params.push(("type".to_string(), type_val.to_string()));
87        }
88
89        let _use_auth = with_auth.unwrap_or(false);
90
91        self.get("/catalog/search", &params).await
92    }
93}
qobuz_api_rust/api/content/catalog.rs

qobuz_api_rust/api/content/
catalog.rs
