Search Endpoint Reference

Functions

Package contains functions to interact with Search endpoints.

async search_for_item(client: SpotanticClient, *, query: str, item_type: Sequence[SpotifyItemType], market: SpotifyMarketID | None = None, limit: int = 10, offset: int = 0, include_external: SearchForItemIncludeExternal | None = None) → APICallModel[SearchForItemRequest, JsonAPIResponse, SearchForItemResponse]

Search for specified items based on a provided query.

Get Spotify catalog information about albums, artists, playlists, tracks, shows, episodes or audiobooks that match a keyword string. Audiobooks are only available within the US, UK, Canada, Ireland, New Zealand and Australia markets.

Parameters:

  • client – SpotanticClient instance.

  • query – Your search query.

  • item_type – A list of item types to search across. Search results include hits from all the specified item types.

  • market – An ISO 3166-1 alpha-2 country code.

  • limit – The maximum number of results to return in each item type.

  • offset – The index of the first result to return. Use with limit to get the next page of search results.

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

Returns:

An object containing the request used to obtain the response, the retrieved data and parsed data as model.

Request models

Package contains request models for Search endpoints.

class SearchForItemIncludeExternal(*values)

Bases: str, Enum

Allowed values for include_external attribute.

AUDIO = 'audio'

It signals that the client can play externally hosted audio content, and marks the content as playable in the response.

class SearchForItemRequest(*, required_scopes: set[AuthScope] = <factory>, url: HttpUrl | None = None, endpoint: str | None = 'search', method_type: HTTPMethod = <HTTPMethod.GET>, headers: RequestHeadersModel = <factory>, params: SearchForItemRequestParams | None = None, body: None = None)

Bases: RequestModel[SearchForItemRequestParams, NoneType]

Request model for Search For Item endpoint.

classmethod build(*, query: str, item_type: Sequence[SpotifyItemType], market: SpotifyMarketID | None = None, limit: int | None = None, offset: int | None = None, include_external: SearchForItemIncludeExternal | None = None) → SearchForItemRequest

Builds a request model based on given parameters.

The function automatically determines the endpoint if it is not static. Also, it automatically assigns parameters to request query or body.

Parameters:

  • query – Your search query.

  • item_type – A list of item types to search across. Search results include hits from all the specified item types.

  • market – An ISO 3166-1 alpha-2 country code.

  • limit – The maximum number of results to return in each item type.

  • offset – The index of the first result to return. Use with limit to get the next page of search results.

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

Returns:

Validated Request object.

endpoint: str | None

Endpoint associated with the request.

method_type: HTTPMethod

HTTP method for the request.

class SearchForItemRequestParams(*, query: str, item_type: Annotated[Sequence[SpotifyItemType], PlainSerializer(func=sequence_to_comma_separated_str, return_type=str, when_used=always)], market: SpotifyMarketID | None = None, limit: Annotated[int | None, Ge(ge=1), Le(le=10)] = None, offset: Annotated[int | None, Ge(ge=0), Le(le=1000)] = None, include_external: SearchForItemIncludeExternal | None = None)

Bases: BaseModel

Params model for Search For Item request.

classmethod validate_type_param(value: Sequence[SpotifyItemType]) → Sequence[SpotifyItemType]

Verifies that all of the specified item types are supported.

The request supports only: albums, artists, playlists, tracks, shows, episodes or audiobooks.

Parameters:

value – The item_type provided by an user.

Returns:

Unchanged input value after validation.

Raises:

ValueError – If provided item_type contains unsupported types.

include_external: SearchForItemIncludeExternal | None

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

item_type: Annotated[Sequence[SpotifyItemType], Field(serialization_alias='type'), PlainSerializer(sequence_to_comma_separated_str, return_type=str)]

A list of item types to search across. Search results include hits from all the specified item types.

limit: Annotated[int | None, Field(ge=1, le=10)]

The maximum number of results to return in each item type.

market: SpotifyMarketID | None

An ISO 3166-1 alpha-2 country code.

offset: Annotated[int | None, Field(ge=0, le=1000)]

The index of the first result to return. Use with limit to get the next page of search results.

query: str

Your search query.

Response models

Package contains response models for Search endpoints.

class SearchForItemResponse(*, tracks: PagedResultModel[TrackModel] | None = None, artists: PagedResultModel[ArtistModel] | None = None, albums: PagedResultModel[SimplifiedAlbumModel] | None = None, playlists: PagedResultModel[SimplifiedPlaylistModel] | None = None, shows: PagedResultModel[SimplifiedShowModel] | None = None, episodes: PagedResultModel[SimplifiedEpisodeModel] | None = None)

Bases: BaseModel

Response model for Search For Item endpoint.

albums: PagedResultModel[SimplifiedAlbumModel] | None

List of albums.

artists: PagedResultModel[ArtistModel] | None

List of atrists.

episodes: PagedResultModel[SimplifiedEpisodeModel] | None

List of episodes.

playlists: PagedResultModel[SimplifiedPlaylistModel] | None

List of playlists.

shows: PagedResultModel[SimplifiedShowModel] | None

List of shows.

tracks: PagedResultModel[TrackModel] | None

List of tracks.