DeezerAPIClient

class minim.api.deezer.DeezerAPIClient(*, auth_flow: str | None = None, app_id: str | None = None, app_secret: str | None = None, user_identifier: str | None = None, redirect_uri: str | None = None, permissions: str | Collection[str] = '', access_token: str | None = None, expires_at: str | datetime | None = None, redirect_handler: str | None = None, open_browser: bool = False, enable_cache: bool = True, limit_rate: bool = True, store_tokens: bool = True, user_agent: str | None = None)

Bases: OAuth2APIClient

Deezer API client.

Parameters:

auth_flowstr; keyword-only

Authorization flow.

Valid values:

• None – No authentication.

• "auth_code" – Authorization Code Flow.

• "implicit" – Implicit Grant Flow.

app_idstr; keyword-only; optional

Application ID. Required unless set as system environment variable DEEZER_API_APP_ID or stored in the local token storage.

app_secretstr; keyword-only; optional

Application secret. Required for the Authorization Code flow unless set as system environment variable DEEZER_API_APP_SECRET or stored in the local token storage.

user_identifierstr; keyword-only; optional

Identifier for the user account. Used when store_tokens=True to distinguish between multiple accounts for the same client ID and authorization flow.

If specified, it is used with the client ID and authorization flow to locate a matching stored token. If none is found, a new token is obtained and stored under this identifier.

If not specified, the most recently accessed token for the client ID and authorization flow is used. If none exists, a new token is obtained and stored using the Deezer user ID acquired from a successful authorization.

Prefixing the identifier with a tilde (~) bypasses token retrieval, forces reauthorization, and stores the new token under the suffix.

redirect_uristr; keyword-only; optional

Redirect URI. Required for the Authorization Code and Authorization Code with PKCE flows.

permissionsstr or Collection[str]; keyword-only; optional

Permissions requested by the client to access user resources.

See also

resolve_permissions() – Resolve substrings into a set of permissions.

access_tokenstr; keyword-only; optional

Access token. If provided, the authorization process is bypassed.

expires_atstr or datetime.datetime; keyword-only; optional

Expiration time of the access token. If a string, it must be in ISO 8601 format (%Y-%m-%dT%H:%M:%SZ).

redirect_handlerstr or None; keyword-only; optional

Backend for handling redirects during the authorization flow. Redirect handling is only available for hosts localhost, 127.0.0.1, or ::1.

Valid values:

• None – Show authorization URL in and have the user manually paste the redirect URL into the terminal.

• "http.server" – Run a HTTP server to intercept the redirect after user authorization in any local browser.

• "playwright" – Use a Playwright Firefox browser to complete the user authorization.

open_browserbool; keyword-only; default: False

Whether to automatically open the authorization URL in the default web browser for the Authorization Code flow. If False, the URL is printed to the terminal.

enable_cachebool; keyword-only; default: True

Whether to enable an in-memory time-to-live (TTL) cache with a least recently used (LRU) eviction policy for this client. If True, responses from semi-static endpoints are cached for one minute to one day, depending on their expected update frequency.

See also

clear_cache() – Clear specific or all cache entries for this client.

limit_ratebool; keyword-only; default: True

Whether to enable a token bucket rate limiter for this client.

store_tokensbool; keyword-only; default: True

Whether to enable the local token storage for this client. If True, existing access tokens are retrieved when found in local storage, and newly acquired tokens and their metadata are stored for future retrieval. If False, the client neither retrieves nor stores access tokens.

See also

get_tokens() – Retrieve specific or all stored access tokens for this client.

remove_tokens() – Remove specific or all stored access tokens for this client.

user_agentstr; keyword-only; optional

User-Agent value to include in the headers of HTTP requests.

Methods

clear_cache	Clear specific or all cache entries for this client.
close	Terminate the underlying HTTP client session.
get_country_info	Get configuration and availability information for the Deezer API in the country associated with the current connection.
get_tokens	Retrieve specific or all access tokens and their metadata for this client from local storage.
open	Initialize a new HTTP client session.
remove_tokens	Remove specific or all access tokens and their metadata for this client from local storage.
resolve_permissions	Resolve one or more substrings into a set of permissions.
set_access_token	Set or update the access token and its related metadata.
set_auth_flow	Set or update the authorization flow and related parameters.
set_cache_enabled	Enable or disable the in-memory TTL cache for this client.

Attributes

albums	Albums API endpoints for the Deezer API.
artists	Artists API endpoints for the Deezer API.
charts	Charts API endpoints for the Deezer API.
editorial	Editorial API endpoints for the Deezer API.
episodes	Episodes API endpoints for the Deezer API.
genres	Genres API endpoints for the Deezer API.
playlists	Playlists API endpoints for the Deezer API.
podcasts	Podcasts API endpoints for the Deezer API.
radios	Radios API endpoints for the Deezer API.
search	Search API endpoints for the Deezer API.
tracks	Tracks API endpoints for the Deezer API.
users	Users API endpoints for the Deezer API.
AUTH_URL	Authorization endpoint.
BASE_URL	Base URL for API endpoints.
DEVICE_AUTH_URL	Device authorization endpoint.
TOKEN_URL	Token endpoint.

AUTH_URL = 'https://connect.deezer.com/oauth/auth.php'

Authorization endpoint.

BASE_URL = 'https://api.deezer.com'

Base URL for API endpoints.

DEVICE_AUTH_URL = None

Device authorization endpoint.

TOKEN_URL = 'https://connect.deezer.com/oauth/access_token.php'

Token endpoint.

albums: AlbumsAPI

Albums API endpoints for the Deezer API.

artists: ArtistsAPI

Artists API endpoints for the Deezer API.

charts: ChartsAPI

Charts API endpoints for the Deezer API.

clear_cache(endpoint_methods: str | Callable[..., Any] | Collection[str | Callable[..., Any]] | None = None, /) → None

Clear specific or all cache entries for this client.

Warning

If endpoint_methods is not provided, all cache entries are cleared.

Parameters:

endpoint_methodsstr, Callable, or Collection[str | Callable]; positional-only; optional

Endpoint methods whose cache entries should be cleared.

close() → None

Terminate the underlying HTTP client session.

editorial: EditorialAPI

Editorial API endpoints for the Deezer API.

episodes: EpisodesAPI

Episodes API endpoints for the Deezer API.

genres: GenresAPI

Genres API endpoints for the Deezer API.

get_country_info() → dict[str, Any]

Get configuration and availability information for the Deezer API in the country associated with the current connection.

Returns:

infodict[str, Any]

Configuration and availability information.

Sample response

{
  "ads": {
    "audio": {
      "default": {
        "interval": <int>,
        "start": <int>,
        "unit": <str>
      }
    },
    "big_native_ads_home": {
      "android": {
        "enabled": <bool>
      },
      "android_tablet": {
        "enabled": <bool>
      },
      "ipad": {
        "enabled": <bool>
      },
      "iphone": {
        "enabled": <bool>
      }
    },
    "display": {
      "interstitial": {
        "interval": <int>,
        "start": <int>,
        "unit": <str>
      }
    }
  },
  "country": <str>,
  "country_iso": <str>,
  "has_podcasts": <bool>,
  "hosts": {
    "images": <str>,
    "stream": <str>
  },
  "lyrics_available": <bool>,
  "offers": [],
  "open": <bool>,
  "pop": <str>,
  "upload_token": <str>,
  "upload_token_lifetime": <int>,
  "user_token": <str>
}

classmethod get_tokens(*, auth_flows: str | Collection[str] | None = None, app_ids: str | Collection[str] | None = None, user_identifiers: str | Collection[str] | None = None) → list[dict[str, Any]] | None

Retrieve specific or all access tokens and their metadata for this client from local storage.

Parameters:

auth_flowsstr or Collection[str]; keyword-only; optional

Authorization flows.

app_idsstr or Collection[str]; keyword-only; optional

Application IDs.

user_identifiersstr or Collection[str]; keyword-only; optional

Identifiers for the user accounts.

open() → None

Initialize a new HTTP client session.

playlists: PlaylistsAPI

Playlists API endpoints for the Deezer API.

podcasts: PodcastsAPI

Podcasts API endpoints for the Deezer API.

radios: RadiosAPI

Radios API endpoints for the Deezer API.

classmethod remove_tokens(*, auth_flows: str | Collection[str] | None = None, app_ids: str | Collection[str] | None = None, user_identifiers: str | Collection[str] | None = None) → None

Remove specific or all access tokens and their metadata for this client from local storage.

Warning

If none of auth_flows, app_ids, or user_identifiers are provided, all tokens for this client will be removed from local storage.

Parameters:

auth_flowsstr or Collection[str]; keyword-only; optional

Authorization flows.

app_idsstr or Collection[str]; keyword-only; optional

Application IDs.

user_identifiersstr or Collection[str]; keyword-only; optional

Identifiers for the user accounts.

classmethod resolve_permissions(matches: str | Collection[str] | None = None) → set[str]

Resolve one or more substrings into a set of permissions.

Parameters:

matchesstr or Collection[str]; optional

Substrings to match in the available permissions. If not provided, all available permissions are returned.

Returns:

permissionsset[str]

Permissions.

search: SearchAPI

Search API endpoints for the Deezer API.

set_access_token(access_token: str | None, /, *, expires_at: str | datetime | None = None) → None

Set or update the access token and its related metadata.

Warning

Calling this method replaces all existing values with the provided parameters. Parameters not provided explicitly will be overwritten by their default values.

Parameters:

access_tokenstr or None; positional-only

Access token.

Important

If the access token was acquired via a different authorization flow or client, call set_auth_flow() first to ensure that all other relevant authorization parameters are set correctly.

expires_atstr or datetime.datetime; keyword-only; optional

Expiration time of the access token. If a string, it must be in ISO 8601 format (%Y-%m-%dT%H:%M:%SZ).

set_auth_flow(auth_flow: str | None, /, *, app_id: str | None = None, app_secret: str | None = None, user_identifier: str | None = None, redirect_uri: str | None = None, permissions: str | Collection[str] = '', redirect_handler: str | None = None, open_browser: bool = False, store_tokens: bool = True, authenticate: bool = True) → None

Set or update the authorization flow and related parameters.

Warning

Calling this method replaces all existing values with the provided parameters. Parameters not provided explicitly will be overwritten by their default values.

Parameters:

auth_flowstr or None; keyword-only

Authorization flow.

Valid values:

• None – No authentication.

• "auth_code" – Authorization Code Flow.

• "implicit" – Implicit Grant Flow.

app_idstr; keyword-only; optional

Application ID. Required unless set as system environment variable DEEZER_API_APP_ID.

app_secretstr; keyword-only; optional

Application secret. Required for the Authorization Code flow unless set as system environment variable DEEZER_API_APP_SECRET.

user_identifierstr; keyword-only; optional

Identifier for the user account. Used when store_tokens=True to distinguish between multiple accounts for the same client ID and authorization flow.

If specified, it is used with the client ID and authorization flow to locate a matching stored token. If none is found, a new token is obtained and stored under this identifier.

If not specified, the most recently accessed token for the client ID and authorization flow is used. If none exists, a new token is obtained and stored using a user identifier (e.g., user ID) acquired from a successful authorization.

Prefixing the identifier with a tilde (~) bypasses token retrieval, forces reauthorization, and stores the new token under the suffix.

redirect_uristr; keyword-only; optional

Redirect URI. Required for the Authorization Code and Implicit Grant flows.

permissionsstr or Collection[str]; keyword-only; optional

Permissions requested by the client to access user resources.

redirect_handlerstr or None; keyword-only; optional

Backend for handling redirects during the authorization flow. Redirect handling is only available for hosts localhost, 127.0.0.1, or ::1.

Valid values:

• None – Show authorization URL in and have the user manually paste the redirect URL into the terminal.

• "http.server" – Run a HTTP server to intercept the redirect after user authorization in any local browser.

• "playwright" – Use a Playwright Firefox browser to complete the user authorization.

open_browserbool; keyword-only; default: False

Whether to automatically open the authorization URL in the default web browser for the Authorization Code and Implicit Grant flows. If False, the URL is printed to the terminal.

store_tokensbool; keyword-only; default: True

Whether to enable the local token storage for this client. If True, existing access tokens are retrieved when found in local storage, and newly acquired tokens and their metadata are stored for future retrieval. If False, the client neither retrieves nor stores access tokens.

See also

get_tokens() – Retrieve specific or all stored access tokens for this client.

remove_tokens() – Remove specific or all stored access tokens for this client.

authenticatebool; keyword-only; default: True

Whether to immediately initiate the authorization flow to acquire an access token.

Important

Unless set_access_token() is called immediately after, this should be left as True to ensure the client’s existing token is compatible with the new authorization flow and/or scopes.

set_cache_enabled(enable: bool, /) → None

Enable or disable the in-memory TTL cache for this client.

Parameters:

enablebool; positional-only

Whether to enable the cache.

tracks: TracksAPI

Tracks API endpoints for the Deezer API.

users: UsersAPI

Users API endpoints for the Deezer API.