SearchAPI

class minim.api.deezer.SearchAPI(client: APIClient, /)[source]

Bases: DeezerResourceAPI

Search API endpoints for the Deezer API.

Important

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

Parameters:
clientminim.api._shared.APIClient

API client instance used to make HTTP requests.

Methods

get_my_search_history

Search > History: Get the current user's search history on Deezer.

search_albums

Search > Album: Search for albums in the Deezer catalog.

search_artists

Search > Artist: Search for artists in the Deezer catalog.

search_playlists

Search > Playlist: Search for playlists in the Deezer catalog.

search_podcasts

Search > Podcast: Search for podcasts in the Deezer catalog.

search_radios

Search > Radio: Search for radios in the Deezer catalog.

search_tracks

Search > Track: Search for tracks in the Deezer catalog.

search_users

Search > User: Search for users on Deezer.
get_my_search_history(query: str | None = None, /, *, strict: bool | None = None, limit: int | None = None, offset: int | None = None, sort_by: str | None = None, descending: bool = False) → dict[str, Any][source]

Search > History: Get the current user’s search history on Deezer.

User authentication

User authentication

Access the GET /search/history endpoint.

Parameters:
querystr; positional-only; optional

Search query.

strictbool; keyword-only; optional

Whether to use strict matching instead of fuzzy search.

API default: False.

limitint; keyword-only; optional

Maximum number of searches to return.

Minimum value: 1.

offsetint; keyword-only; optional

Index of the first search to return. Use with limit to get the next batch of searches.

Minimum value: 0.

API default: 0.

sort_bystr; keyword-only; optional

Field to sort the returned searches by.

Valid values: "RANKING", "TRACK", "ARTIST", "ALBUM", "RATING", "DURATION".

descendingbool; keyword-only; default: False

Whether to sort in descending order. Only applicable when sort_by is not "RANKING".

Returns:
searchesdict[str, Any]

Page of Deezer metadata for the current user’s search history.

Sample response

{
  "count": <int>,
  "data": [],
  "next": <str>,
  "prev": <str>,
  "total": <int>
}
search_albums(query: str, /, *, strict: bool | None = None, limit: int | None = None, offset: int | None = None, sort_by: str | None = None, descending: bool = False) → dict[str, Any][source]

Search > Album: Search for albums in the Deezer catalog.

Parameters:
querystr; positional-only

Search query.

Tip

Use the Advanced Search feature to narrow down results by specific fields. Provide key–value pairs separated by a colon (:), and wrap strings in quotes:

  • artist - Artist name, e.g., artist:"aloe blacc".

  • album - Album name, e.g., album:"good things".

  • track - Track name, e.g., track:"i need a dollar".

  • label - Label name, e.g., label:"because music".

  • dur_min / dur_max - Track duration in seconds, e.g., dur_min:300 dur_max:500.

  • bpm_min / bpm_max - Track tempo (BPM), e.g., bpm_min:120 bpm_max:200.

Example: artist:"aloe blacc" track:"i need a dollar" bpm_min:120 dur_min:300.

strictbool; keyword-only; optional

Whether to use strict matching instead of fuzzy search.

API default: False.

limitint; keyword-only; optional

Maximum number of albums to return.

Minimum value: 1.

offsetint; keyword-only; optional

Index of the first album to return. Use with limit to get the next batch of albums.

Minimum value: 0.

API default: 0.

sort_bystr; keyword-only; optional

Field to sort the returned albums by.

Valid values: "RANKING", "TRACK", "ARTIST", "ALBUM", "RATING", "DURATION".

descendingbool; keyword-only; default: False

Whether to sort in descending order. Only applicable when sort_by is not "RANKING".

Returns:
albumsdict[str, Any]

Page of Deezer metadata for the matching albums.

Sample response

{
  "data": [
    {
      "artist": {
        "id": <int>,
        "link": <str>,
        "name": <str>,
        "picture": <str>,
        "picture_big": <str>,
        "picture_medium": <str>,
        "picture_small": <str>,
        "picture_xl": <str>,
        "tracklist": <str>,
        "type": "artist"
      },
      "cover": <str>,
      "cover_big": <str>,
      "cover_medium": <str>,
      "cover_small": <str>,
      "cover_xl": <str>,
      "explicit_lyrics": <bool>,
      "genre_id": <int>,
      "id": <int>,
      "link": <str>,
      "md5_image": <str>,
      "nb_tracks": <int>,
      "record_type": <str>,
      "title": <str>,
      "tracklist": <str>,
      "type": "album"
    }
  ],
  "next": <str>,
  "prev": <str>,
  "total": <int>
}
search_artists(query: str, /, *, strict: bool | None = None, limit: int | None = None, offset: int | None = None, sort_by: str | None = None, descending: bool = False) → dict[str, Any][source]

Search > Artist: Search for artists in the Deezer catalog.

Parameters:
querystr; positional-only

Search query.

Tip

Use the Advanced Search feature to narrow down results by specific fields. Provide key–value pairs separated by a colon (:), and wrap strings in quotes:

  • artist - Artist name, e.g., artist:"aloe blacc".

  • album - Album name, e.g., album:"good things".

  • track - Track name, e.g., track:"i need a dollar".

  • label - Label name, e.g., label:"because music".

  • dur_min / dur_max - Track duration in seconds, e.g., dur_min:300 dur_max:500.

  • bpm_min / bpm_max - Track tempo (BPM), e.g., bpm_min:120 bpm_max:200.

Example: artist:"aloe blacc" track:"i need a dollar" bpm_min:120 dur_min:300.

strictbool; keyword-only; optional

Whether to use strict matching instead of fuzzy search.

API default: False.

limitint; keyword-only; optional

Maximum number of artists to return.

Minimum value: 1.

offsetint; keyword-only; optional

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

Minimum value: 0.

API default: 0.

sort_bystr; keyword-only; optional

Field to sort the returned artists by.

Valid values: "RANKING", "TRACK", "ARTIST", "ALBUM", "RATING", "DURATION".

descendingbool; keyword-only; default: False

Whether to sort in descending order. Only applicable when sort_by is not "RANKING".

Returns:
artistsdict[str, Any]

Page of Deezer metadata for the matching artists.

Sample response

{
  "data": [
    {
      "id": <int>,
      "link": <str>,
      "name": <str>,
      "nb_album": <int>,
      "nb_fan": <int>,
      "picture": <str>,
      "picture_big": <str>,
      "picture_medium": <str>,
      "picture_small": <str>,
      "picture_xl": <str>,
      "radio": <bool>,
      "tracklist": <str>,
      "type": "artist"
    }
  ],
  "next": <str>,
  "prev": <str>,
  "total": <int>
}
search_playlists(query: str, /, *, strict: bool | None = None, limit: int | None = None, offset: int | None = None, sort_by: str | None = None, descending: bool = False) → dict[str, Any][source]

Search > Playlist: Search for playlists in the Deezer catalog.

Parameters:
querystr; positional-only

Search query.

strictbool; keyword-only; optional

Whether to use strict matching instead of fuzzy search.

API default: False.

limitint; keyword-only; optional

Maximum number of playlists to return.

Minimum value: 1.

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.

sort_bystr; keyword-only; optional

Field to sort the returned playlists by.

Valid values: "RANKING", "TRACK", "ARTIST", "ALBUM", "RATING", "DURATION".

descendingbool; keyword-only; default: False

Whether to sort in descending order. Only applicable when sort_by is not "RANKING".

Returns:
playlistsdict[str, Any]

Page of Deezer metadata for the matching playlists.

Sample response

{
  "data": [
    {
      "add_date": <str>,
      "checksum": <str>,
      "creation_date": <str>,
      "id": <int>,
      "link": <str>,
      "md5_image": <str>,
      "mod_date": <str>,
      "nb_tracks": <int>,
      "picture": <str>,
      "picture_big": <str>,
      "picture_medium": <str>,
      "picture_small": <str>,
      "picture_type": <str>,
      "picture_xl": <str>,
      "public": <bool>,
      "title": <str>,
      "tracklist": <str>,
      "type": <str>,
      "user": {
        "id": <int>,
        "name": <str>,
        "tracklist": <str>,
        "type": "user"
      }
    }
  ],
  "next": <str>,
  "prev": <str>,
  "total": <int>
}
search_podcasts(query: str, /, *, strict: bool | None = None, limit: int | None = None, offset: int | None = None, sort_by: str | None = None, descending: bool = False) → dict[str, Any][source]

Search > Podcast: Search for podcasts in the Deezer catalog.

Parameters:
querystr; positional-only

Search query.

strictbool; keyword-only; optional

Whether to use strict matching instead of fuzzy search.

API default: False.

limitint; keyword-only; optional

Maximum number of podcasts to return.

Minimum value: 1.

offsetint; keyword-only; optional

Index of the first podcast to return. Use with limit to get the next batch of podcasts.

Minimum value: 0.

API default: 0.

sort_bystr; keyword-only; optional

Field to sort the returned podcasts by.

Valid values: "RANKING", "TRACK", "ARTIST", "ALBUM", "RATING", "DURATION".

descendingbool; keyword-only; default: False

Whether to sort in descending order. Only applicable when sort_by is not "RANKING".

Returns:
podcastsdict[str, Any]

Page of Deezer metadata for the matching podcasts.

Sample response

{
  "data": [
    {
      "available": <bool>,
      "description": <str>,
      "fans": <int>,
      "id": <int>,
      "link": <str>,
      "picture": <str>,
      "picture_big": <str>,
      "picture_medium": <str>,
      "picture_small": <str>,
      "picture_xl": <str>,
      "share": <str>,
      "title": <str>,
      "type": "podcast"
    }
  ],
  "next": <str>,
  "prev": <str>,
  "total": <int>
}
search_radios(query: str, /, *, strict: bool | None = None, limit: int | None = None, offset: int | None = None, sort_by: str | None = None, descending: bool = False) → dict[str, Any][source]

Search > Radio: Search for radios in the Deezer catalog.

Parameters:
querystr; positional-only

Search query.

strictbool; keyword-only; optional

Whether to use strict matching instead of fuzzy search.

API default: False.

limitint; keyword-only; optional

Maximum number of radios to return.

Minimum value: 1.

offsetint; keyword-only; optional

Index of the first radio to return. Use with limit to get the next batch of radios.

Minimum value: 0.

API default: 0.

sort_bystr; keyword-only; optional

Field to sort the returned radios by.

Valid values: "RANKING", "TRACK", "ARTIST", "ALBUM", "RATING", "DURATION".

descendingbool; keyword-only; default: False

Whether to sort in descending order. Only applicable when sort_by is not "RANKING".

Returns:
radiosdict[str, Any]

Page of Deezer metadata for the matching radios.

Sample response

{
  "data": [
    {
      "id": <int>,
      "md5_image": <str>,
      "picture": <str>,
      "picture_big": <str>,
      "picture_medium": <str>,
      "picture_small": <str>,
      "picture_xl": <str>,
      "title": <str>,
      "tracklist": <str>,
      "type": "radio"
    }
  ],
  "next": <str>,
  "prev": <str>,
  "total": <int>
}
search_tracks(query: str, /, *, strict: bool | None = None, limit: int | None = None, offset: int | None = None, sort_by: str | None = None, descending: bool = False) → dict[str, Any][source]

Search > Track: Search for tracks in the Deezer catalog.

Parameters:
querystr; positional-only

Search query.

Tip

Use the Advanced Search feature to narrow down results by specific fields. Provide key–value pairs separated by a colon (:), and wrap strings in quotes:

  • artist - Artist name, e.g., artist:"aloe blacc".

  • album - Album name, e.g., album:"good things".

  • track - Track name, e.g., track:"i need a dollar".

  • label - Label name, e.g., label:"because music".

  • dur_min / dur_max - Track duration in seconds, e.g., dur_min:300 dur_max:500.

  • bpm_min / bpm_max - Track tempo (BPM), e.g., bpm_min:120 bpm_max:200.

Example: artist:"aloe blacc" track:"i need a dollar" bpm_min:120 dur_min:300.

strictbool; keyword-only; optional

Whether to use strict matching instead of fuzzy search.

API default: False.

limitint; keyword-only; optional

Maximum number of tracks to return.

Minimum value: 1.

API default: 25.

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.

sort_bystr; keyword-only; optional

Field to sort the returned tracks by.

Valid values: "RANKING", "TRACK", "ARTIST", "ALBUM", "RATING", "DURATION".

descendingbool; keyword-only; default: False

Whether to sort in descending order. Only applicable when sort_by is not "RANKING".

Returns:
tracksdict[str, Any]

Page of Deezer metadata for the matching tracks.

Sample response

{
  "data": [
    {
      "album": {
        "cover": <str>,
        "cover_big": <str>,
        "cover_medium": <str>,
        "cover_small": <str>,
        "cover_xl": <str>,
        "id": <int>,
        "md5_image": <str>,
        "title": <str>,
        "tracklist": <str>,
        "type": "album"
      },
      "artist": {
        "id": <int>,
        "link": <str>,
        "name": <str>,
        "picture": <str>,
        "picture_big": <str>,
        "picture_medium": <str>,
        "picture_small": <str>,
        "picture_xl": <str>,
        "tracklist": <str>,
        "type": "artist"
      },
      "duration": <int>,
      "explicit_content_cover": <int>,
      "explicit_content_lyrics": <int>,
      "explicit_lyrics": <bool>,
      "id": <int>,
      "link": <str>,
      "md5_image": <str>,
      "preview": <str>,
      "rank": <int>,
      "readable": <bool>,
      "title": <str>,
      "title_short": <str>,
      "title_version": <str>,
      "type": "track"
    }
  ],
  "next": <str>,
  "prev": <str>,
  "total": <int>
}
search_users(query: str, /, *, strict: bool | None = None, limit: int | None = None, offset: int | None = None, sort_by: str | None = None, descending: bool = False) → dict[str, Any][source]

Search > User: Search for users on Deezer.

Parameters:
querystr; positional-only

Search query.

strictbool; keyword-only; optional

Whether to use strict matching instead of fuzzy search.

API default: False.

limitint; keyword-only; optional

Maximum number of users to return.

Minimum value: 1.

API default: 25.

offsetint; keyword-only; optional

Index of the first user to return. Use with limit to get the next batch of users.

Minimum value: 0.

API default: 0.

sort_bystr; keyword-only; optional

Field to sort the returned users by.

Valid values: "RANKING", "TRACK", "ARTIST", "ALBUM", "RATING", "DURATION".

descendingbool; keyword-only; default: False

Whether to sort in descending order. Only applicable when sort_by is not "RANKING".

Returns:
usersdict[str, Any]

Page of Deezer metadata for the matching users.

Sample response

{
  "data": [
    {
      "id": <int>,
      "name": <str>,
      "picture": <str>,
      "picture_big": <str>,
      "picture_medium": <str>,
      "picture_small": <str>,
      "picture_xl": <str>,
      "tracklist": <str>,
      "type": "user"
    }
  ],
  "next": <str>,
  "prev": <str>,
  "total": <int>
}