JS Spotify API

A javascript wrapper for Spotify's Web API.

Browser Support

| | | | | | | | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | 67+ ✔ | 52+ ✔ | 16+ ✔ | 54+ ✔ | 16+ ✔ | 11 ✔ |

Table of Contents

• Features
• Dependencies
• Installation
• Usage
• Api
• Development

Features

The library includes helper functions to do the following:

Note: Most of them are still in progress to make (sections marked with TODO)

Music metadata

• Albums, artists, and tracks
• Audio features and analysis for tracks (todo)
• Albums for a specific artist todo
• Top tracks for a specific artist todo
• Artists similar to a specific artist todo

Profiles todo

• User's emails, product type, display name, birthdate, image

Search

• albums
• artists, tracks, and playlists (todo)

Playlist manipulation (todo)

• Get a user's playlists
• Create playlists
• Change playlist details
• Add tracks to a playlist
• Remove tracks from a playlist
• Replace tracks in a playlist
• Reorder tracks in a playlist

Your Music library (todo)

• Add, remove, and get tracks and albums that are in the signed in user's Your Music library
• Check if a track or album is in the signed in user's Your Music library

Personalization (todo)

• Get a user’s top artists and tracks based on calculated affinity

Browse (todo)

• Get New Releases
• Get Featured Playlists
• Get a List of Categories
• Get a Category
• Get a Category's Playlists
• Get recommendations based on seeds
• Get available genre seeds

Follow (todo)

• Follow and unfollow users
• Follow and unfollow artists
• Check if the logged in user follows a user or artist
• Follow a playlist
• Unfollow a playlist
• Get followed artists
• Check if users are following a Playlist

Player (todo)

• Get a user's available devices
• Get information about the user's current playback
• Get current user’s recently played tracks
• Transfer a user's playback
• Resume a user's playback
• Skip a user's playback to next track
• Skip a user's playback to previous track
• Set a user's shuffle mode
• Set a user's repeat mode
• Set volume
• Seek playback to a given position

All methods require authentication, which can be done using these flows:

• Client credentials flow (Application-only authentication)
• Authorization code grant (Signed by user)

Dependencies

• To use this library you will need a node version >= 6.0.0.

• Download one of the follows Node Version Managers to manage the node versions easily:

  • nvm
  • n

Installation

From npm

$ npm i -S js-spotify-api

From git

    $ git clone https://github.com/rubengomex/js-spotify-api.git
    $ cd js-spotify-api
    $ npm i

Tests

You can run the tests by running the follow command:

    $ npm t

Note: You only can run the tests if you clone the repository from github

Usage

ES6

// to import a specific method
import Spotify from 'js-spotify-api'

const spotify = new Spotify({
  token: 'YOUR_TOKEN_HERE'
})

// using  method
spotify.getArtists({ band: 'Incubus' }).then(artists => console.log(artists))

CommonJS

const Spotify = require('js-spotify-api')

const spotify = new Spotify({
  token: 'YOUR_TOKEN_HERE'
})

UMD in Browser

<!-- to import non-minified version -->
<script src="js-spotify-api.umd.js"></script>

<!-- to import minified version -->
<script src="js-spotify-api.umd.min.js"></script>

After that the library will be available to the Global as Spotify. Follow an example:

const spotify = new Spotify({
  token: 'YOUR_TOKEN_HERE'
})

let albums
spotify
  .getAlbums({ artist: 'Chosen artist' })
  .then(albumsFromArtists => (albums = albumsFromArtists))
  .catch(err => console.log(err))

console.log(albums)

// Want to use async/await? Add the `async` keyword to your outer function/method.
async function getUser() {
  try {
    const response = await spotify.getAlbums({ artists: 'Chosen artist' })
    console.log(response)
  } catch (error) {
    console.error(error)
  }
}

NOTE: async/await is part of ECMAScript 2017 and is not supported in Internet Explorer and older browsers, so use with caution.

API

Table of Contents

• Spotify
  • Parameters
  • getAlbums
    • Parameters
    • Examples
  • getAlbum
    • Parameters
    • Examples
  • getAlbumTracks
    • Parameters
    • Examples

Spotify

Parameters

• opts object Specifies the options for spotify class
  • opts.token string Specifies the spotify token to use

Meta

• author: Rúben Gomes <[email protected]>

getAlbums

Gets albums info based on albums ids specified

Parameters

• opts object Specifies the options object
  • opts.ids Array<string> Specifies the spotify albums ids

Examples

Albums
[{
   album_type: 'album',
   artists: [ [Object] ],
   available_markets: ['AD', 'EC', 'PT', ...],
   copyrights: [ [Object] ],
   external_ids: { upc: '886445352382' },
   external_urls: { spotify: 'https://open.spotify.com/album/{albumId}'}
   ...
}]

Returns Promise<Array<object>> The albums information

getAlbum

Gets album info based on the id of the album

Parameters

• opts object Specifies the options object
  • opts.id string Specifies the spotify album id

Examples

Album
{
   album_type: 'album',
   artists: [ [Object] ],
   available_markets: ['AD', 'EC', 'PT', ...],
   copyrights: [ [Object] ],
   external_ids: { upc: '886445352382' },
   external_urls: { spotify: 'https://open.spotify.com/album/{albumId}'}
   ...
}

Returns Promise<object> The album information

getAlbumTracks

Gets the tracks of the album info based on the id of the album

Parameters

• opts object Specifies the options object
  • opts.id string Specifies the spotify album id
  • opts.skip number Specifies the offset of the items to retrieve (optional, default 0)
  • opts.limit number Specifies the limit of items to retrieve (optional, default 20)

Examples

Tracks
[{
   artists: [ [Object] ],
   available_markets: ['AD', 'EC', 'PT', ...],
   copyrights: [ [Object] ],
   disc_number: 1,
   track_number: 1
   ...
}]

Returns Promise<Array<object>> The album tracks information

Development

See something you think can be improved? Please open an issue for that 😎