Reference#

Clients#

placeholder text

Client#

class spotipy.Client(client_id: str, client_secret: str, session: Optional[ClientSession] = None)#
await get_album(_id: str, /, *, market: Optional[str] = None, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → Album#
await get_albums(ids: Sequence[ID], *, market: Optional[str] = None, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → dict[ID, spotipy.objects.album.Album | None]#
await get_album_tracks(_id: str, /, *, market: Optional[str] = None, limit: Optional[int] = None, offset: Optional[int] = None, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → list[spotipy.objects.track.SimpleTrack]#
await get_all_album_tracks(_id: str, /, *, market: Optional[str] = None, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → list[spotipy.objects.track.SimpleTrack]#
await get_full_album(_id: str, /, *, market: Optional[str] = None, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → Album#
await get_saved_albums() → ...#
await save_albums() → ...#
await remove_albums() → ...#
await check_saved_albums() → ...#
await get_new_releases(*, country: Optional[str] = None, limit: Optional[int] = None, offset: Optional[int] = None, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → list[spotipy.objects.album.SimpleAlbum]#
await get_artist(_id: str, /, *, market: Optional[str] = None, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → Artist#
await get_artists(ids: Sequence[ID], *, market: Optional[str] = None, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → dict[ID, spotipy.objects.artist.Artist | None]#
await get_artist_albums(_id: str, /, *, market: Optional[str] = None, include_groups: Optional[list[spotipy.enums.IncludeGroup]] = None, limit: Optional[int] = None, offset: Optional[int] = None, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → list[spotipy.objects.album.SimpleAlbum]#
await get_all_artist_albums(_id: str, /, *, market: Optional[str] = None, include_groups: Optional[list[spotipy.enums.IncludeGroup]] = None, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → list[spotipy.objects.album.SimpleAlbum]#
await get_artist_top_tracks(_id: str, /, *, market: str, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → list[spotipy.objects.track.Track]#
await get_show(_id: str, /, *, market: str, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → Show#
await get_shows(ids: Sequence[ID], *, market: str, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → dict[ID, spotipy.objects.show.Show | None]#
await get_show_episodes(_id: str, /, *, market: str, limit: Optional[int] = None, offset: Optional[int] = None, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → list[spotipy.objects.episode.SimpleEpisode]#
await get_all_show_episodes(_id: str, /, *, market: str, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → list[spotipy.objects.episode.SimpleEpisode]#
await get_saved_shows() → ...#
await save_shows() → ...#
await remove_shows() → ...#
await check_saved_shows() → ...#
await get_episode(_id: str, /, *, market: str | None = 'GB', credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → Episode#
await get_episodes(ids: Sequence[ID], *, market: str | None = 'GB', credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → dict[ID, spotipy.objects.episode.Episode | None]#
await get_saved_episodes() → ...#
await save_episodes() → ...#
await remove_episodes() → ...#
await check_saved_episodes() → ...#
await get_track(_id: str, /, *, market: Optional[str] = None, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → Track#
await get_tracks(ids: Sequence[ID], *, market: Optional[str] = None, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → dict[ID, spotipy.objects.track.Track | None]#
await get_saved_tracks() → ...#
await save_tracks() → ...#
await remove_tracks() → ...#
await check_saved_tracks() → ...#
await get_multiple_tracks_audio_features(ids: Sequence[ID], *, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → dict[ID, spotipy.objects.track.AudioFeatures | None]#
await get_track_audio_features(_id: str, /, *, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → AudioFeatures#
await get_track_audio_analysis() → ...#
await get_recommendations(*, seed_artist_ids: Optional[list[str]] = None, seed_track_ids: Optional[list[str]] = None, seed_genres: Optional[list[str]] = None, limit: Optional[int] = None, market: Optional[str] = None, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None, **kwargs: int) → Recommendations#
await search(query: str, /, *, search_types: Optional[list[spotipy.enums.SearchType]] = None, market: Optional[str] = None, limit: Optional[int] = None, offset: Optional[int] = None, include_external: bool = False, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → SearchResult#
await get_current_user_profile(*, credentials: UserCredentials) → User#
await get_current_users_top_artists(*, time_range: spotipy.enums.TimeRange | None, limit: int | None, offset: int | None, credentials: UserCredentials) → list[spotipy.objects.artist.Artist]#
await get_current_users_top_tracks(*, time_range: Optional[TimeRange] = None, limit: Optional[int] = None, offset: Optional[int] = None, credentials: UserCredentials) → list[spotipy.objects.track.Track]#
await get_user_profile(_id: str, /, *, credentials: UserCredentials) → User#
await follow_playlist() → ...#
await unfollow_playlist() → ...#
await get_followed_artists() → ...#
await get_followed_users() → ...#
await follow_artists() → ...#
await follow_users() → ...#
await unfollow_artists() → ...#
await unfollow_users() → ...#
await check_followed_artists() → ...#
await check_followed_users() → ...#
await check_playlist_followers() → ...#
await get_playlist(_id: str, /, *, market: Optional[str] = None, fields: Optional[str] = None, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → Playlist#
await change_playlist_details() → ...#
await get_playlist_items(_id: str, /, *, market: Optional[str] = None, fields: Optional[str] = None, limit: Optional[int] = None, offset: Optional[int] = None, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → list[spotipy.objects.track.PlaylistTrack]#
await get_all_playlist_items(_id: str, /, *, market: Optional[str] = None, fields: Optional[str] = None, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → list[spotipy.objects.track.PlaylistTrack]#
await get_full_playlist(_id: str, /, *, market: Optional[str] = None, fields: Optional[str] = None, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → Playlist#
await add_items_to_playlist() → ...#
await reorder_playlist_items() → ...#
await replace_playlist_items() → ...#
await remove_items_from_playlist() → ...#
await get_current_user_playlists(*, limit: Optional[int] = None, offset: Optional[int] = None, credentials: UserCredentials) → list[spotipy.objects.playlist.SimplePlaylist]#
await get_all_current_user_playlists(*, credentials: UserCredentials) → list[spotipy.objects.playlist.SimplePlaylist]#
await get_user_playlists(_id: str, /, *, limit: Optional[int] = None, offset: Optional[int] = None, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → list[spotipy.objects.playlist.SimplePlaylist]#
await get_all_user_playlists(_id: str, /, *, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → list[spotipy.objects.playlist.SimplePlaylist]#
await create_playlist() → ...#
await get_category_playlists(_id: str, /, *, country: Optional[str] = None, limit: Optional[int] = None, offset: Optional[int] = None, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → list[spotipy.objects.playlist.SimplePlaylist]#
await get_playlist_cover_image(_id: str, /, *, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → list[spotipy.objects.image.Image]#
await upload_playlist_cover_image() → ...#
await get_categories(*, country: Optional[str] = None, locale: Optional[str] = None, limit: Optional[int] = None, offset: Optional[int] = None, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → list[spotipy.objects.category.Category]#
await get_category(_id: str, /, *, country: Optional[str] = None, locale: Optional[str] = None, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → Category#
await get_available_genre_seeds(*, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → list[str]#
await get_playback_state() → ...#
await transfer_playback() → ...#
await get_available_devices() → ...#
await get_currently_playing_track() → ...#
await start_playback() → ...#
await resume_playback() → ...#
await pause_playback() → ...#
await skip_to_next() → ...#
await skip_to_previous() → ...#
await seek_to_position() → ...#
await set_repeat_mode() → ...#
await set_playback_volume() → ...#
await toggle_playback_shuffle() → ...#
await get_recently_played_tracks() → ...#
await add_item_to_playback_queue() → ...#
await get_available_markets(*, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → list[str]#

HTTPClient#

class spotipy.HTTPClient(*, client_id: str, client_secret: str, session: Optional[ClientSession] = None)#
await close() → None#
await request(route: Route, /, *, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None, query: Optional[dict[str, Any]] = None, body: Optional[str] = None, json: Optional[dict[str, Any]] = None) → Any#
await get_album(_id: str, /, *, market: str | None, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → AlbumData#
await get_multiple_albums(ids: Sequence[str], /, *, market: str | None, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → dict[Literal['albums'], list[spotipy.objects.album.AlbumData | None]]#
await get_album_tracks(_id: str, /, *, limit: int | None, offset: int | None, market: str | None, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → PagingObjectData[SimpleTrackData]#
await get_saved_albums(*, limit: int | None, offset: int | None, market: str | None, credentials: UserCredentials) → PagingObjectData[AlbumData]#
await save_albums(ids: list[str], /, *, credentials: UserCredentials) → None#
await remove_albums(ids: list[str], /, *, credentials: UserCredentials) → None#
await check_saved_albums(ids: list[str], /, *, credentials: UserCredentials) → list[bool]#
await get_new_releases(*, country: str | None, limit: int | None, offset: int | None, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → dict[Literal['albums'], spotipy.objects.base.PagingObjectData[spotipy.objects.album.SimpleAlbumData]]#
await get_artist(_id: str, /, *, market: str | None, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → ArtistData#
await get_multiple_artists(ids: Sequence[str], /, *, market: str | None, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → dict[Literal['artists'], list[spotipy.objects.artist.ArtistData | None]]#
await get_artist_albums(_id: str, /, *, include_groups: list[spotipy.enums.IncludeGroup] | None, limit: int | None, offset: int | None, market: str | None, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → PagingObjectData[SimpleAlbumData]#
await get_artist_top_tracks(_id: str, /, *, market: str, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → dict[Literal['tracks'], list[spotipy.objects.track.TrackData]]#
await get_show(_id: str, /, *, market: str, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → ShowData#
await get_multiple_shows(ids: Sequence[str], /, *, market: str, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → dict[Literal['shows'], list[spotipy.objects.show.ShowData | None]]#
await get_show_episodes(_id: str, /, *, limit: int | None, offset: int | None, market: str, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → PagingObjectData[EpisodeData]#
await get_saved_shows(*, limit: int | None, offset: int | None, credentials: UserCredentials) → PagingObjectData[ShowData]#
await save_shows(ids: list[str], /, *, credentials: UserCredentials) → None#
await remove_shows(ids: list[str], /, *, credentials: UserCredentials) → None#
await check_saved_shows(ids: list[str], /, *, credentials: UserCredentials) → list[bool]#
await get_episode(_id: str, /, *, market: str | None, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → EpisodeData#
await get_multiple_episodes(ids: Sequence[str], /, *, market: str | None, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → dict[Literal['episodes'], list[spotipy.objects.episode.EpisodeData | None]]#
await get_saved_episodes(*, limit: int | None, offset: int | None, market: str | None, credentials: UserCredentials) → PagingObjectData[EpisodeData]#
await save_episodes(ids: list[str], /, *, credentials: UserCredentials) → None#
await remove_episodes(ids: list[str], /, *, credentials: UserCredentials) → None#
await check_saved_episodes(ids: list[str], /, *, credentials: UserCredentials) → list[bool]#
await get_track(_id: str, /, *, market: str | None, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → TrackData#
await get_multiple_tracks(ids: Sequence[str], *, market: str | None, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → dict[Literal['tracks'], list[spotipy.objects.track.TrackData | None]]#
await get_saved_tracks(*, limit: int | None, offset: int | None, market: str | None, credentials: UserCredentials) → PagingObjectData[TrackData]#
await save_tracks(ids: list[str], /, *, credentials: UserCredentials) → None#
await remove_tracks(ids: list[str], /, *, credentials: UserCredentials) → None#
await check_saved_tracks(ids: list[str], /, *, credentials: UserCredentials) → list[bool]#
await get_track_audio_features(_id: str, /, *, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → AudioFeaturesData#
await get_multiple_tracks_audio_features(ids: Sequence[str], /, *, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → dict[Literal['audio_features'], list[spotipy.objects.track.AudioFeaturesData | None]]#
await get_track_audio_analysis(_id: str, /, *, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → dict[str, Any]#
await get_recommendations(*, seed_artist_ids: list[str] | None, seed_track_ids: list[str] | None, seed_genres: list[str] | None, limit: int | None, market: str | None, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None, **kwargs: int) → RecommendationsData#
await search(_query: str, /, *, search_types: list[spotipy.enums.SearchType], include_external: bool, limit: int | None, offset: int | None, market: str | None, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → SearchResultData#
await get_current_user_profile(*, credentials: UserCredentials) → UserData#
await get_current_user_top_artists(*, limit: int | None, offset: int | None, time_range: spotipy.enums.TimeRange | None, credentials: UserCredentials) → PagingObjectData[ArtistData]#
await get_current_user_top_tracks(*, limit: int | None, offset: int | None, time_range: spotipy.enums.TimeRange | None, credentials: UserCredentials) → PagingObjectData[TrackData]#
await get_user_profile(_id: str, /, *, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → UserData#
await follow_playlist(_id: str, /, *, public: bool, credentials: UserCredentials) → None#
await unfollow_playlist(_id: str, /, *, credentials: UserCredentials) → None#
await check_if_users_follow_playlist(_id: str, /, *, user_ids: list[str], credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → None#
await get_followed_artists(*, limit: int | None, after: str | None, credentials: UserCredentials) → AlternativePagingObjectData[ArtistData]#
await follow_artists(ids: list[str], /, *, credentials: UserCredentials) → None#
await unfollow_artists(ids: list[str], /, *, credentials: UserCredentials) → None#
await check_followed_artists(ids: list[str], /, *, credentials: UserCredentials) → list[bool]#
await follow_users(ids: list[str], /, *, credentials: UserCredentials) → None#
await unfollow_users(ids: list[str], /, *, credentials: UserCredentials) → None#
await check_followed_users(ids: list[str], /, *, credentials: UserCredentials) → list[bool]#
await get_playlist(_id: str, /, *, fields: str | None, market: str | None, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → PlaylistData#
await change_playlist_details(_id: str, /, *, name: str | None, public: bool | None, collaborative: bool | None, description: str | None, credentials: UserCredentials) → None#
await get_playlist_items(_id: str, /, *, fields: str | None, limit: int | None, offset: int | None, market: str | None, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → PagingObjectData[PlaylistTrackData]#
await add_items_to_playlist(_id: str, /, *, uris: list[str], position: int | None, credentials: UserCredentials) → PlaylistSnapshotID#
await reorder_playlist_items(_id: str, /, *, range_start: int, range_length: int, insert_before: int, snapshot_id: str | None, credentials: UserCredentials) → PlaylistSnapshotID#
await replace_playlist_items(_id: str, /, *, uris: list[str], credentials: UserCredentials) → None#
await remove_items_from_playlist(_id: str, /, *, uris: list[str], snapshot_id: str | None, credentials: UserCredentials) → PlaylistSnapshotID#
await get_current_user_playlists(*, limit: int | None, offset: int | None, credentials: UserCredentials) → PagingObjectData[SimplePlaylistData]#
await get_user_playlists(_id: str, /, *, limit: int | None, offset: int | None, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → PagingObjectData[SimplePlaylistData]#
await create_playlist(*, user_id: str, name: str, public: bool | None, collaborative: bool | None, description: str | None, credentials: UserCredentials) → PlaylistData#
await get_category_playlists(_id: str, /, *, limit: int | None, offset: int | None, country: str | None, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → dict[Literal['playlists'], spotipy.objects.base.PagingObjectData[spotipy.objects.playlist.SimplePlaylistData]]#
await get_playlist_cover_image(_id: str, /, *, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → list[spotipy.objects.image.ImageData]#
await upload_playlist_cover_image(_id: str, /, *, url: str, credentials: UserCredentials) → None#
await get_categories(*, limit: int | None, offset: int | None, locale: str | None, country: str | None, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → dict[Literal['categories'], spotipy.objects.base.PagingObjectData[spotipy.objects.category.CategoryData]]#
await get_category(_id: str, /, *, locale: str | None, country: str | None, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → CategoryData#
await get_available_genre_seeds(*, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → dict[Literal['genres'], list[str]]#
await get_playback_state(*, market: str | None, credentials: UserCredentials) → PlaybackStateData#
await transfer_playback(*, device_id: str, ensure_playback: bool | None, credentials: UserCredentials) → None#
await get_available_devices(*, credentials: UserCredentials) → dict[Literal['devices'], list[spotipy.objects.device.DeviceData]]#
await get_currently_playing_track(*, market: str | None, credentials: UserCredentials) → CurrentlyPlayingData#
await start_playback(*, device_id: str | None, context_uri: str | None, uris: list[str] | None, offset: int | str | None, position_ms: int | None, credentials: UserCredentials) → None#
await resume_playback(*, device_id: str | None, offset: int | str | None, position_ms: int | None, credentials: UserCredentials) → None#
await pause_playback(*, device_id: str | None, credentials: UserCredentials) → None#
await skip_to_next(*, device_id: str | None, credentials: UserCredentials) → None#
await skip_to_previous(*, device_id: str | None, credentials: UserCredentials) → None#
await seek_to_position(*, position_ms: int, device_id: str | None, credentials: UserCredentials) → None#
await set_repeat_mode(*, repeat_mode: RepeatMode, device_id: str | None, credentials: UserCredentials) → None#
await set_playback_volume(*, volume_percent: int, device_id: str | None, credentials: UserCredentials) → None#
await toggle_playback_shuffle(*, state: bool, device_id: str | None, credentials: UserCredentials) → None#
await get_recently_played_tracks(*, limit: int | None, before: int | None, after: int | None, credentials: UserCredentials) → AlternativePagingObjectData[SimpleTrackData]#
await add_item_to_playback_queue(*, uri: str, device_id: str | None, credentials: UserCredentials) → None#
await get_available_markets(*, credentials: Optional[Union[ClientCredentials, UserCredentials]] = None) → dict[Literal['markets'], list[str]]#