SearchAPI

class minim.api.spotify.SearchAPI(client: APIClient, /)

Bases: SpotifyResourceAPI

Search API endpoints for the Spotify Web API.

Important

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

Parameters:

clientminim.api._shared.APIClient

API client instance used to make HTTP requests.

Methods

search

Search > Search for Item: Search for albums, artists, playlists, tracks, shows, episodes, and/or audiobooks in the Spotify catalog.

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

Search > Search for Item: Search for albums, artists, playlists, tracks, shows, episodes, and/or audiobooks in the Spotify catalog.

Important

Audiobooks are only available in the US, UK, Canada, Ireland, New Zealand, and Australia markets.

Third-party application mode

Optional

Extended quota mode before November 27, 2024

Access 30-second preview URLs. Learn more.

Parameters:

querystr, positional-only

Search query.

Tip

Searches can be narrowed using field filters, such as album, artist, track, year, upc, tag:hipster, tag:new, isrc, and genre. Each filter applies only to certain result types:

• artist and year can be used when searching albums, artists and tracks. The year filter accepts a year or a range (e.g., "year:1955-1960").

• album can be used when searching albums and tracks.

• genre can be used when searching artists and tracks.

• isrc and track can be used when searching tracks.

• upc, tag:new, and tag:hipster can be used when searching albums. The tag:new filter returns albums released in the past two weeks, and the tag:hipster filter returns albums in the lowest 10% popularity.

Example: "remaster track:Doxy artist:Miles Davis".

item_typesstr or Collection[str]

Types of items to return.

Valid values: "album", "artist", "playlist", "track", "show", "episode", "audiobook".

Examples: "artist", "track,episode", ["album", "playlist"].

external_contentstr; keyword-only; optional

Externally hosted content that the client can play.

Valid value: "audio".

country_codestr; keyword-only; optional

ISO 3166-1 alpha-2 country code. If provided, only content available in that market is returned. When a user access token accompanies the request, the country associated with the user account takes priority over this parameter.

Note

If neither a country code is provided nor a country can be determined from the user account, the content is considered unavailable for the client.

Example: "ES".

limitint; keyword-only; optional

Maximum number of items to return.

Valid range: 1 to 10.

API default: 5.

offsetint; keyword-only; optional

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

Valid range: 0 to 1_000.

Minimum value: 0.

API default: 0.

Returns:

itemsdict[str, Any]

Page of Spotify metadata for the matching catalog items.

Sample response

{
  "albums": {
    "href": <str>,
    "items": [
      {
        "album_type": <str>,
        "artists": [
          {
            "external_urls": {
              "spotify": <str>
            },
            "href": <str>,
            "id": <str>,
            "name": <str>,
            "type": "artist",
            "uri": <str>
          }
        ],
        "external_urls": {
          "spotify": <str>
        },
        "href": <str>,
        "id": <str>,
        "images": [
          {
            "height": <int>,
            "url": <str>,
            "width": <int>
          }
        ],
        "is_playable": <bool>,
        "name": <str>,
        "release_date": <str>,
        "release_date_precision": <str>,
        "total_tracks": <int>,
        "type": "album",
        "uri": <str>
      }
    ],
    "limit": <int>,
    "next": <str>,
    "offset": <int>,
    "previous": <int>,
    "total": <int>
  },
  "artists": {
    "href": <str>,
    "items": [
      {
        "external_urls": {
          "spotify": <str>
        },
        "followers": {
          "href": <str>,
          "total": <int>
        },
        "genres": <list[str]>,
        "href": <str>,
        "id": <str>,
        "images": [
          {
            "height": <int>,
            "url": <str>,
            "width": <int>
          }
        ],
        "name": <str>,
        "popularity": <int>,
        "type": "artist",
        "uri": <str>
      }
    ],
    "limit": <int>,
    "next": <str>,
    "offset": <int>,
    "previous": <int>,
    "total": <int>
  },
  "audiobooks": {
    "href": <str>,
    "items": [
      {
        "authors": [
          {
            "name": <str>
          }
        ],
        "copyrights": <list[str]>,
        "description": <str>,
        "edition": <str>,
        "explicit": <bool>,
        "external_urls": {
          "spotify": <str>
        },
        "href": <str>,
        "html_description": <str>,
        "id": <str>,
        "images": [
          {
            "height": <int>,
            "url": <str>,
            "width": <int>
          }
        ],
        "is_externally_hosted": <bool>,
        "languages": <list[str]>,
        "media_type": <str>,
        "name": <str>,
        "narrators": [
          {
            "name": <str>
          }
        ],
        "publisher": <str>,
        "total_chapters": <int>,
        "type": "audiobook",
        "uri": <str>
      }
    ],
    "limit": <int>,
    "next": <str>,
    "offset": <int>,
    "previous": <int>,
    "total": <int>
  },
  "episodes": {
    "href": <str>,
    "items": [
      {
        "audio_preview_url": <str>,
        "description": <str>,
        "duration_ms": <int>,
        "explicit": <bool>,
        "external_urls": {
          "spotify": <str>
        },
        "href": <str>,
        "html_description": <str>,
        "id": <str>,
        "images": [
          {
            "height": <int>,
            "url": <str>,
            "width": <int>
          }
        ],
        "is_externally_hosted": <bool>,
        "is_playable": <bool>,
        "language": <str>,
        "languages": <list[str]>,
        "name": <str>,
        "release_date": <str>,
        "release_date_precision": <str>,
        "resume_point": {
          "fully_played": <bool>,
          "resume_position_ms": <int>
        },
        "type": "episode",
        "uri": <str>
      }
    ],
    "limit": <int>,
    "next": <str>,
    "offset": <int>,
    "previous": <int>,
    "total": <int>
  },
  "playlists": {
    "href": <str>,
    "items": [
      {
        "collaborative": <bool>,
        "description": <str>,
        "external_urls": {
          "spotify": <str>
        },
        "href": <str>,
        "id": <str>,
        "images": [
          {
            "height": <int>,
            "url": <str>,
            "width": <int>
          }
        ],
        "name": <str>,
        "owner": {
          "display_name": <str>,
          "external_urls": {
            "spotify": <str>
          },
          "href": <str>,
          "id": <str>,
          "type": "user",
          "uri": <str>
        },
        "primary_color": <str>,
        "public": <bool>,
        "snapshot_id": <str>,
        "tracks": {
          "href": <str>,
          "total": <int>
        },
        "type": "playlist",
        "uri": <str>
      }
    ],
    "limit": <int>,
    "next": <str>,
    "offset": <int>,
    "previous": <int>,
    "total": <int>
  },
  "shows": {
    "href": <str>,
    "items": [
      {
        "copyrights": <list[str]>,
        "description": <str>,
        "explicit": <bool>,
        "external_urls": {
          "spotify": <str>
        },
        "href": <str>,
        "html_description": <str>,
        "id": <str>,
        "images": [
          {
            "height": <int>,
            "url": <str>,
            "width": <int>
          }
        ],
        "is_externally_hosted": <bool>,
        "languages": <list[str]>,
        "media_type": <str>,
        "name": <str>,
        "publisher": <str>,
        "total_episodes": <int>,
        "type": "show",
        "uri": <str>
      }
    ],
    "limit": <int>,
    "next": <str>,
    "offset": <int>,
    "previous": <int>,
    "total": <int>
  },
  "tracks": {
    "href": <str>,
    "items": [
      {
        "album": {
          "album_type": <str>,
          "artists": [
            {
              "external_urls": {
                "spotify": <str>
              },
              "href": <str>,
              "id": <str>,
              "name": <str>,
              "type": "artist",
              "uri": <str>
            }
          ],
          "external_urls": {
            "spotify": <str>
          },
          "href": <str>,
          "id": <str>,
          "images": [
            {
              "height": <int>,
              "url": <str>,
              "width": <int>
            }
          ],
          "is_playable": <bool>,
          "name": <str>,
          "release_date": <str>,
          "release_date_precision": <str>,
          "total_tracks": <int>,
          "type": "album",
          "uri": <str>
        },
        "artists": [
          {
            "external_urls": {
              "spotify": <str>
            },
            "href": <str>,
            "id": <str>,
            "name": <str>,
            "type": "artist",
            "uri": <str>
          }
        ],
        "disc_number": <int>,
        "duration_ms": <int>,
        "explicit": <bool>,
        "external_ids": {
          "isrc": <str>
        },
        "external_urls": {
          "spotify": <str>
        },
        "href": <str>,
        "id": <str>,
        "is_local": <bool>,
        "is_playable": <bool>,
        "name": <str>,
        "popularity": <int>,
        "preview_url": <str>,
        "track_number": <int>,
        "type": "track",
        "uri": <str>
      }
    ],
    "limit": <int>,
    "next": <str>,
    "offset": <int>,
    "previous": <int>,
    "total": <int>
  }
}