Skip to content

Search

API #

Implementation to make API calls with.

Parameters:

search_for_item #

search_for_item(*, types: list[SearchType], query: MissingOr[str] = MISSING, album: MissingOr[str] = MISSING, artist: MissingOr[str] = MISSING, track: MissingOr[str] = MISSING, start_year: MissingOr[int] = MISSING, end_year: MissingOr[int] = MISSING, upc: MissingOr[str] = MISSING, hipster: MissingOr[bool] = MISSING, new: MissingOr[bool] = MISSING, isrc: MissingOr[str] = MISSING, genres: MissingOr[list[str]] = MISSING, market: MissingOr[str] = MISSING, limit: MissingOr[int] = MISSING, offset: MissingOr[int] = MISSING, include_external: MissingOr[bool] = MISSING) -> SearchResult

Get Spotify catalog information about albums, artists, playlists, tracks, shows, episodes or audiobooks that match the search query.

Parameters:

  • types (list[SearchType]) –

    Type of items to search for.

  • query (str, default: MISSING ) –

    The search query.

  • album (str, default: MISSING ) –

    The album. Can be used while searching albums and tracks.

  • artist (str, default: MISSING ) –

    The artist. Can be used while searching albums, artists and tracks.

  • track (str, default: MISSING ) –

    The track. Can be used while searching tracks.

    Note

    start_year and end_year can be used to create a range of years to search across.

  • start_year (int, default: MISSING ) –

    The year, or start year if also using end_year. Can be used while searching albums, artists and tracks.

  • end_year (int, default: MISSING ) –

    The end year. If supplied, start_year must also be supplied. Can be used while searching albums, artists and tracks.

  • upc (str, default: MISSING ) –

    The Universal Product Code for the item. Can be used while searching albums.

  • hipster (bool, default: MISSING ) –

    If True, get albums with the lowest 10% popularity. Can be used while searching albums.

  • new (bool, default: MISSING ) –

    If True, get albums released within the past 2 weeks. Can be used while searching albums.

  • isrc (str, default: MISSING ) –

    The International Standard Recording Code for the item. Can be used while searching tracks.

  • genres (list[str], default: MISSING ) –

    The genre(s). Can be used while searching artists and tracks.

  • market (str, default: MISSING ) –

    Only get content available in that market. Must be an ISO 3166-1 alpha-2 country code.

  • limit (int, default: 20 ) –

    The maximum number of results to return in each item type. Default: 20. Minimum: 0. Maximum: 50.

  • offset (int, default: 0 ) –

    The index of the first item to return. Default: 0 (the first item).

  • include_external (bool, default: MISSING ) –

    If set to True it signals that the client can play externally hosted audio content, and marks the content as playable in the response.

Returns:

SearchResult #

A search result.

tracks #

tracks: Paginator[TrackWithSimpleArtist] | None = None

Returned tracks.

artists #

artists: Paginator[Artist] | None = None

Returned artists.

albums #

albums: Paginator[SimpleAlbum] | None = None

Returned albums.

playlists #

playlists: Paginator[SimplePlaylist] | None = None

Returned playlists.

shows #

shows: Paginator[SimpleShow | None] | None = None

Returned shows.

episodes #

episodes: Paginator[SimpleEpisode] | None = None

Returned episodes.

audiobooks #

audiobooks: Paginator[SimpleAudiobook] | None = None

Returned audiobooks.