spotify-web-client

A fully typed client for node and browser environments.

🚀 Quick Start

Install:

# npm
npm i spotify-web-client

# yarn
yarn add spotify-web-client

Import:

// ESM / Typescript
import { SpotifyClient } from 'spotify-web-client'

// CommonJS
const { SpotifyClient } = require('spotify-web-client')

Usage

const token = '...' // Generate an access token with OAuth

const client = new SpotifyClient().setAccessToken(token)

// Get currently played song
const playbackState = await client.player.getPlaybackState()
if (playbackState.item?.type === 'track') {
  // playbackState.item narrowed to TrackObject
  console.log(playbackState.item.name)
}

You can check for more advanced usage (OAuth, other methods...) in the playground directory

📦 Available APIs

• 🔒 Authentication
• 💿 Albums
• 🎤 Artists
• 📗 Audiobooks
• 🔖 Categories
• 🕮 Chapters
• 🎙️ Episodes
• 🪩 Genres
• 🌍 Markets
• ▶️ Player
• 🎧 Playlists
• 🔍 Search
• 🎙️ Shows
• 🎼 Tracks
• 👥 Users

🔒 Authentication

These methods can be accessed directly through your SpotifyClient instance.

Method	Description
setAccessToken	Sets the access_token for the current instance of SpotifyClient
setRefreshToken	Sets the refresh_token for the current instance of SpotifyClient
generateOAuthUrl	Generates an OAuth link with the provided scope
getAccessToken	Exchanges an authorization code for an access_token and a refresh_token
refreshToken	Obtain a new access_token from a refresh token

💿 Albums

These methods can be accessed through the albums key of your SpotifyClient instance.

Method	Description
getAlbum	Get Spotify catalog information for a single album.
getAlbums	Get Spotify catalog information for multiple albums identified by their Spotify IDs.
getAlbumTracks	Get Spotify catalog information about an album’s tracks. Optional parameters can be used to limit the number of tracks returned.
getSavedAlbums	Get a list of the albums saved in the current Spotify user's 'Your Music' library.
saveAlbums	Save one or more albums to the current user's 'Your Music' library.
removeAlbums	Remove one or more albums from the current user's 'Your Music' library.
checkUserSavedAlbums	Check if one or more albums is already saved in the current Spotify user's 'Your Music' library.
getReleases	Get a list of new album releases featured in Spotify (shown, for example, on a Spotify player’s “Browse” tab).

🎤 Artists

These methods can be accessed through the artists key of your SpotifyClient instance.

Method	Description
getArtist	Get Spotify catalog information for a single artist identified by their unique Spotify ID.
getArtists	Get Spotify catalog information for several artists based on their Spotify IDs.
getArtistAlbums	Get Spotify catalog information about an artist's albums.
getArtistTopTracks	Get Spotify catalog information about an artist's top tracks by country.
getRelatedArtists	Get Spotify catalog information about artists similar to a given artist. Similarity is based on analysis of the Spotify community's listening history.

📗 Audiobooks

These methods can be accessed through the audiobooks key of your SpotifyClient instance.

Note: Audiobooks are only available for the US, UK, Ireland, New Zealand and Australia markets.

Method	Description
getAudiobook	Get Spotify catalog information for a single audiobook.
getAudiobooks	Get Spotify catalog information for several audiobooks identified by their Spotify IDs.
getAudiobookChapters	Get Spotify catalog information about an audiobook's chapters.
getSavedAudiobooks	Get a list of the audiobooks saved in the current Spotify user's 'Your Music' library.
saveAudiobooks	Save one or more audiobooks to the current Spotify user's library.
removeAudiobooks	Remove one or more audiobooks from the Spotify user's library.
checkUserSavedAudiobooks	Check if one or more audiobooks are already saved in the current Spotify user's library.

🔖 Categories

These methods can be accessed through the categories key of your SpotifyClient instance.

Method	Description
getCategories	Get a list of categories used to tag items in Spotify (on, for example, the Spotify player’s “Browse” tab).
getCategory	Get a single category used to tag items in Spotify (on, for example, the Spotify player’s “Browse” tab).

🕮 Chapters

These methods can be accessed through the chapters key of your SpotifyClient instance.

Note: Chapters are only available for the US, UK, Ireland, New Zealand and Australia markets.

Method	Description
getChapter	Get Spotify catalog information for a single chapter.
getChapters	Get Spotify catalog information for several chapters identified by their Spotify IDs.

🎙️ Episodes

These methods can be accessed through the episodes key of your SpotifyClient instance.

Method	Description
getEpisode	Get Spotify catalog information for a single episode identified by its unique Spotify ID.
getEpisodes	Get Spotify catalog information for several episodes based on their Spotify IDs.
getSavedEpisodes	Get a list of the episodes saved in the current Spotify user's library.
saveEpisodes	Save one or more episodes to the current user's library.
removeEpisodes	Remove one or more episodes from the current user's library.
checkUserSavedEpisodes	Check if one or more episodes is already saved in the current Spotify user's 'Your Episodes' library.

🪩 Genres

These methods can be accessed through the genres key of your SpotifyClient instance.

Method	Description
getAvailableGenreSeeds	Retrieve a list of available genres seed parameter values for recommendations.

🌍 Markets

These methods can be accessed through the genres key of your SpotifyClient instance.

Method	Description
getMarkets	Get the list of markets where Spotify is available.

▶️ Player

These methods can be accessed through the player key of your SpotifyClient instance.

Method	Description
getPlaybackState	Get information about the user’s current playback state, including track or episode, progress, and active device.
transferPlayback	Transfer playback to a new device and determine if it should start playing.
getAvailableDevices	Get information about a user’s available devices.
getCurrentlyPlayedTrack	Get the object currently being played on the user's Spotify account.
startPlayback	Start a new context or resume current playback on the user's active device.
pausePlayback	Pause playback on the user's account.
skipToNext	Skips to next track in the user’s queue.
skipToPrevious	Skips to previous track in the user’s queue.
seekToPosition	Seeks to the given position in the user’s currently playing track.
setRepeatMode	Set the repeat mode for the user's playback. Options are repeat-track, repeat-context, and off.
setPlaybackVolume	Set the volume for the user’s current playback device.
toggleShuffle	Toggle shuffle on or off for user’s playback.
getRecentlyPlayedTracks	Get tracks from the current user's recently played tracks.
getUserQueue	Get the list of objects that make up the user's queue.
addItemToQueue	Add an item to the end of the user's current playback queue.

🎧 Playlists

These methods can be accessed through the playlists key of your SpotifyClient instance.

Method	Description
getPlaylist	Get a playlist owned by a Spotify user.
updatePlaylistDetails	Change a playlist's name and public/private state. (The user must, of course, own the playlist.)
getPlaylistItems	Get full details of the items of a playlist owned by a Spotify user.
updatePlaylistItems	Either reorder or replace items in a playlist depending on the request's parameters. To reorder items, include range_start, insert_before, range_length and snapshot_id in the request's body. To replace items, include uris as either a query parameter or in the request's body. Replacing items in a playlist will overwrite its existing items. This operation can be used for replacing or clearing items in a playlist.
addPlaylistItems	Add one or more items to a user's playlist.
removePlaylistItems	Remove one or more items from a user's playlist.
getCurrentUserPlaylists	Get a list of the playlists owned or followed by the current Spotify user.
getUserPlaylists	Get a list of the playlists owned or followed by a Spotify user.
createPlaylist	Create a playlist for a Spotify user. (The playlist will be empty until you add tracks.)
getFeaturedPlaylists	Get a list of Spotify featured playlists (shown, for example, on a Spotify player's 'Browse' tab).
getPlaylistsForCategory	Get a list of Spotify playlists tagged with a particular category.
getPlaylistCoverImage	Get the current image associated with a specific playlist.
addCustomPlaylistCoverImage	Replace the image used to represent a specific playlist.

🔍 Search

These methods can be accessed through the search key of your SpotifyClient instance.

Note: Audiobooks are only available for the US, UK, Ireland, New Zealand and Australia markets.

Method	Description
search	Get Spotify catalog information about albums, artists, playlists, tracks, shows, episodes or audiobooks that match a keyword string.

🎙️ Shows

These methods can be accessed through the shows key of your SpotifyClient instance.

Method	Description
getShow	Get Spotify catalog information for a single show identified by its unique Spotify ID.
getShows	Get Spotify catalog information for several shows based on their Spotify IDs.
getShowsEpisodes	Get Spotify catalog information about an show’s episodes. Optional parameters can be used to limit the number of episodes returned.
getSavedShows	Get a list of shows saved in the current Spotify user's library. Optional parameters can be used to limit the number of shows returned.
saveShows	Save one or more shows to current Spotify user's library.
removeShows	Delete one or more shows from current Spotify user's library.
checkUserSavedShows	Check if one or more shows is already saved in the current Spotify user's library.

🎼 Tracks

These methods can be accessed through the tracks key of your SpotifyClient instance.

Method	Description
getTrack	Get Spotify catalog information for a single track identified by its unique Spotify ID.
getTracks	Get Spotify catalog information for multiple tracks based on their Spotify IDs.
getUserSavedTracks	Get a list of the songs saved in the current Spotify user's 'Your Music' library.
saveTracks	Save one or more tracks to the current user's 'Your Music' library.
removeSavedTracks	Remove one or more tracks from the current user's 'Your Music' library.
checkUserSavedTracks	Check if one or more tracks is already saved in the current Spotify user's 'Your Music' library.
getTracksAudioFeatures	Get audio features for multiple tracks based on their Spotify IDs.
getTrackAudioFeatures	Get audio feature information for a single track identified by its unique Spotify ID.
getTrackAudioAnalysis	Get a low-level audio analysis for a track in the Spotify catalog. The audio analysis describes the track’s structure and musical content, including rhythm, pitch, and timbre.
getRecommendations	Recommendations are generated based on the available information for a given seed entity and matched against similar artists and tracks. If there is sufficient information about the provided seeds, a list of tracks will be returned together with pool size details. For artists and tracks that are very new or obscure there might not be enough data to generate a list of tracks.

👥 Users

These methods can be accessed through the users key of your SpotifyClient instance.

Method	Description
getCurrentUserProfile	Get detailed profile information about the current user (including the current user's username).
getCurrentUserTopItems	Get the current user's top artists or tracks based on calculated affinity.
getUserProfile	Get public profile information about a Spotify user.
followPlaylist	Add the current user as a follower of a playlist.
unfollowPlaylist	Remove the current user as a follower of a playlist.
getFollowedArtists	Get the current user's followed artists.
follow	Add the current user as a follower of one or more artists or other Spotify users.
unfollow	Remove the current user as a follower of one or more artists or other Spotify users.
isFollowing	Check to see if the current user is following one or more artists or other Spotify users.
isFollowingPlaylist	Check to see if one or more Spotify users are following a specified playlist.