Skip to main content

​
Overview

The AsyncSearchService provides powerful search capabilities across Spotify’s entire catalog. Search for tracks, albums, artists, playlists, shows, episodes, and audiobooks with flexible query syntax and filtering options.
This service is available in both async (AsyncSearchService) and sync (SearchService) variants.
Search for items across multiple resource types in the Spotify catalog. 
async def search(
    self,
    q: str,
    types: list[SearchType],
    market: str | None = None,
    limit: int = 5,
    offset: int = 0,
    include_external: IncludeExternal | None = None,
) -> SearchResult
​
q
str
required
Search query with keywords and optional filters.Query syntax:
  • Simple keyword: "remaster track:Doxy artist:Miles Davis"
  • Field filters: album:arrival artist:abba
  • Year filters: year:2015-2020 or year:2020
  • Genre: genre:"indie rock"
  • Tag filters: tag:hipster, tag:new
  • Boolean operators: roadhouse AND blues
  • Negation: roadhouse NOT blues
  • Wildcards: bus* (matches “bus”, “business”, “busy”)
​
types
list[SearchType]
required
List of resource types to search for.Valid types:
  • "album" - Albums
  • "artist" - Artists
  • "playlist" - Playlists
  • "track" - Tracks
  • "show" - Podcasts/Shows
  • "episode" - Podcast episodes
  • "audiobook" - Audiobooks
Example: ["track", "artist", "album"]
​
market
str | None
An ISO 3166-1 alpha-2 country code. If provided, only content available in that market is returned.Example: "US", "GB", "CA"
​
limit
int
Maximum number of results to return per type. Default: 5. Range: 0-50.
​
offset
int
Index of the first result to return. Default: 0. Use with limit for pagination.
​
include_external
IncludeExternal | None
Whether to include externally hosted audio content.Valid value: "audio"

​
Returns

​
SearchResult
SearchResult
Search results grouped by resource type. Each requested type has a corresponding field:
  • tracks - Page[Track] if “track” was in types
  • albums - Page[SimplifiedAlbum] if “album” was in types
  • artists - Page[Artist] if “artist” was in types
  • playlists - Page[SimplifiedPlaylist] if “playlist” was in types
  • shows - Page[SimplifiedShow] if “show” was in types
  • episodes - Page[SimplifiedEpisode] if “episode” was in types
  • audiobooks - Page[SimplifiedAudiobook] if “audiobook” was in types

​
Examples

from spotify_sdk import SpotifyClient

client = SpotifyClient(auth_token="your_token")

# Search for tracks and artists
results = await client.search.search(
    q="Bohemian Rhapsody",
    types=["track", "artist"]
)

# Access track results
if results.tracks:
    for track in results.tracks.items:
        print(f"Track: {track.name} by {track.artists[0].name}")

# Access artist results
if results.artists:
    for artist in results.artists.items:
        print(f"Artist: {artist.name}")

​
Search Query Syntax

The search query (q parameter) supports powerful filtering and operators:

​
Field Filters

Filter by specific fields: 
# Search for tracks with specific album and artist
q = "album:arrival artist:abba"

# Search for remaster tracks
q = "remaster track:Doxy artist:Miles Davis"

​
Year Filters

Filter by release year: 
# Specific year
q = "year:2020"

# Year range
q = "year:2015-2020"

# Before year
q = "year:0-2000"

​
Genre Filter

q = 'genre:"indie rock"'
q = 'genre:jazz'

​
Tag Filters

# Hipster tag
q = "tag:hipster"

# New releases
q = "tag:new"

​
Boolean Operators

# AND operator (both terms required)
q = "roadhouse AND blues"

# OR operator (either term)
q = "roadhouse OR blues"

# NOT operator (exclude term)
q = "roadhouse NOT blues"

​
Wildcards

# Matches bus, business, busy, etc.
q = "bus*"

​
Complex Queries

Combine multiple filters: 
results = await client.search.search(
    q='year:2015-2020 genre:"indie rock" tag:new',
    types=["track", "album"],
    market="US"
)

​
Search Types Reference

​
SearchType
Literal
Valid search type values:
TypeDescription
"album"Search for albums
"artist"Search for artists
"playlist"Search for playlists
"track"Search for tracks
"show"Search for podcasts/shows
"episode"Search for podcast episodes
"audiobook"Search for audiobooks

​
Error Handling

The search method validates inputs and raises ValueError for: 
try:
    results = await client.search.search(
        q="",  # Empty query
        types=["track"]
    )
except ValueError as e:
    print(f"Error: {e}")  # "q cannot be empty"

try:
    results = await client.search.search(
        q="test",
        types=[]  # Empty types list
    )
except ValueError as e:
    print(f"Error: {e}")  # "types cannot be empty"

try:
    results = await client.search.search(
        q="test",
        types=["invalid_type"]  # Invalid type
    )
except ValueError as e:
    print(f"Error: {e}")  # Lists valid types
When searching for multiple types, use specific field filters in your query to get more relevant results. For example, "artist:Queen track:Bohemian" is better than just "Queen Bohemian".
Search results are paginated with a maximum limit of 50 per type. Use the offset parameter to retrieve additional results.

Build docs developers (and LLMs) love

Get started for freeTalk to us