Search

Search operations live under client.search.

Methods

Method	Returns	Description
`search(q, types, market=None, limit=5, offset=0, include_external=None)`	`SearchResult`	Search Spotify catalog resources by query

Type values

Supported values for types are: album, artist, playlist, track, show, episode, and audiobook.

Examples

SyncAsync

from spotify_sdk import SpotifyClient

with SpotifyClient(access_token="your-access-token") as client:
    result = client.search.search(
        q="kind of blue",
        types=["album", "artist"],
        market="US",
        limit=10,
    )
    albums = result.albums.items if result.albums else []

import asyncio
from spotify_sdk import AsyncSpotifyClient


async def main() -> None:
    async with AsyncSpotifyClient(access_token="your-access-token") as client:
        result = await client.search.search(
            q="kind of blue",
            types=["album", "artist"],
            market="US",
            limit=10,
        )
        artists = result.artists.items if result.artists else []


asyncio.run(main())

API details

The sync client mirrors these methods, minus the await keywords.

Bases: AsyncBaseService

Operations for searching Spotify catalog content.

`search(q, types, market=None, limit=5, offset=0, include_external=None)` `async`

Search for items in the Spotify catalog.

Parameters:

Name	Type	Description	Default
`q`	`str`	Search query keywords and filters.	required
`types`	`list[SearchType]`	Resource types to search.	required
`market`	`str \| None`	An ISO 3166-1 alpha-2 country code.	`None`
`limit`	`int`	Maximum number of results per type (0-10, default 5).	`5`
`offset`	`int`	Index of the first result to return.	`0`
`include_external`	`IncludeExternal \| None`	Whether to include externally hosted audio.	`None`

Returns:

Type	Description
`SearchResult`	Search results grouped by requested type.

Raises:

Type	Description
`ValueError`	If q is empty, types is empty, or types contain unsupported values.