{"id":15034533,"url":"https://github.com/jmperez/spotify-web-api-js","last_synced_at":"2025-05-14T12:07:59.677Z","repository":{"id":16072071,"uuid":"18816479","full_name":"JMPerez/spotify-web-api-js","owner":"JMPerez","description":"A client-side JS wrapper for the Spotify Web API","archived":false,"fork":false,"pushed_at":"2024-05-17T18:10:53.000Z","size":2033,"stargazers_count":1885,"open_issues_count":29,"forks_count":268,"subscribers_count":30,"default_branch":"master","last_synced_at":"2025-05-11T06:52:26.877Z","etag":null,"topics":["api","spotify","spotify-api","spotify-library","spotify-sdk","spotify-web-api","spotify-webapi","wrapper"],"latest_commit_sha":null,"homepage":"https://jmperezperez.com/spotify-web-api-js/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JMPerez.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["JMPerez"],"custom":["https://www.buymeacoffee.com/jmp"]}},"created_at":"2014-04-15T21:24:14.000Z","updated_at":"2025-05-10T02:29:50.000Z","dependencies_parsed_at":"2024-11-06T19:36:26.132Z","dependency_job_id":"e4fe256f-8cfd-46f4-92e7-8fb4a3366f38","html_url":"https://github.com/JMPerez/spotify-web-api-js","commit_stats":{"total_commits":237,"total_committers":30,"mean_commits":7.9,"dds":0.6075949367088608,"last_synced_commit":"79bd5623744fa7022041c7a7429cbd82efc08f83"},"previous_names":[],"tags_count":48,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JMPerez%2Fspotify-web-api-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JMPerez%2Fspotify-web-api-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JMPerez%2Fspotify-web-api-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JMPerez%2Fspotify-web-api-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JMPerez","download_url":"https://codeload.github.com/JMPerez/spotify-web-api-js/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254140756,"owners_count":22021219,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","spotify","spotify-api","spotify-library","spotify-sdk","spotify-web-api","spotify-webapi","wrapper"],"created_at":"2024-09-24T20:25:25.052Z","updated_at":"2025-05-14T12:07:59.617Z","avatar_url":"https://github.com/JMPerez.png","language":"TypeScript","funding_links":["https://github.com/sponsors/JMPerez","https://www.buymeacoffee.com/jmp","https://img.buymeacoffee.com/button-api/?text=Buy"],"categories":[],"sub_categories":[],"readme":"# Spotify Web API JS [![Build Status](https://travis-ci.org/JMPerez/spotify-web-api-js.svg?branch=master)](https://travis-ci.org/JMPerez/spotify-web-api-js) [![Coverage Status](https://coveralls.io/repos/JMPerez/spotify-web-api-js/badge.svg)](https://coveralls.io/r/JMPerez/spotify-web-api-js) [![Greenkeeper badge](https://badges.greenkeeper.io/JMPerez/spotify-web-api-js.svg)](https://greenkeeper.io/) \u003ca href=\"https://www.buymeacoffee.com/jmp\"\u003e\u003cimg src=\"https://img.buymeacoffee.com/button-api/?text=Buy me a coffee\u0026emoji=\u0026slug=jmp\u0026button_colour=BD5FFF\u0026font_colour=ffffff\u0026font_family=Poppins\u0026outline_colour=000000\u0026coffee_colour=FFDD00\" height=\"20\"\u003e\u003c/a\u003e\n\nThis is a lightweight wrapper for the [Spotify Web API](https://developer.spotify.com/web-api/) ([2.6kB gzipped + compressed](https://cost-of-modules.herokuapp.com/result?p=spotify-web-api-js)). It includes helper functions for **all Spotify's endpoints**, such as fetching metadata (search and look-up of albums, artists, tracks, playlists, new releases, podcasts) and user's information (follow users, artists and playlists, and saved tracks management).\n\nIt doesn't have any dependencies and supports callbacks and promises. It is intended to be run on a browser, but if you want to use Node.JS to make the requests, please check [spotify-web-api-node](https://github.com/thelinmichael/spotify-web-api-node).\n\nA list of selected wrappers for different languages and environments is available on the Developer site's [Libraries page](https://developer.spotify.com/web-api/code-examples/).\n\nThe wrapper includes helper functions to do the following:\n\n#### Music and Podcast metadata\n\n- Albums, artists, tracks and playlists\n- Audio features and audio analysis for tracks\n- Albums for a specific artist\n- Top tracks for a specific artist\n- Artists similar to a specific artist\n- Shows and episodes (podcasts)\n\n#### Profiles\n\n- User's emails, product type, display name, birthdate, image\n\n#### Search\n\n- Albums, artists, tracks, playlists, shows, and episodes\n\n#### Playlist Management\n\n- Get a user's playlists\n- Create playlists\n- Change playlist details\n- Add tracks to a playlist\n- Remove tracks from a playlist\n- Replace tracks in a playlist\n- Reorder tracks in a playlist\n- Upload custom playlist cover image\n\n#### User's Library\n\n- Add, remove, and get tracks on a user's library\n- Check if a track is in the signed in user's library\n- Add, remove, and get shows (podcasts) on a user's library\n\n#### Personalization\n\n- Get a user’s top artists and tracks based on calculated affinity\n- Get current user’s recently played tracks\n\n#### Browse\n\n- Get new releases\n- Get featured playlists\n- Get a list of categories\n- Get a category\n- Get a category's playlists\n- Get recommendations based on seeds\n- Get available genre seeds\n\n#### Follow\n\n- Follow and unfollow users\n- Follow and unfollow artists\n- Check if the logged in user follows a user or artist\n- Follow a playlist\n- Unfollow a playlist\n- Get followed artists\n- Check if users are following a Playlist\n\n#### Player\n\n- Get a user's available devices\n- Get information about the user's current playback\n- Get the user's currently playing track\n- Transfer a user's playback\n- Start/Resume a user's playback\n- Pause a user's playback\n- Skip user's playback to next track\n- Skip user's playback to previous track\n- Seek to position in currently playing track\n- Set repeat mode on user's playback\n- Set volume for user's playback\n- Toggle shuffle for user's playback\n- Queue a track or an episode\n\n## Installation\n\nInstall via node (since the requests are made using XMLHttpRequest, you will need a tool like Browserify to run this on a browser):\n\n    $ npm install -S spotify-web-api-js\n\nThen, in your javascript file\n\n```js\nvar Spotify = require('spotify-web-api-js');\nvar s = new Spotify();\n//s.searchTracks()...\n```\n\nor by making a copy of the `src/spotify-web-api.js` file\n\n## Usage\n\nWe recommend you have a look at the [documentation](https://jmperezperez.com/spotify-web-api-js/) to get an overview of the supported\n.\n\nThe wrapper supports callback functions, as well as [Promises](http://www.html5rocks.com/en/tutorials/es6/promises/) (you can also use [a polyfill](https://github.com/jakearchibald/es6-promise)), and Promises/A+ libraries such as [Q](https://github.com/kriskowal/q) and [when](https://github.com/cujojs/when).\n\nFirst, instantiate the wrapper.\n\n```js\nvar spotifyApi = new SpotifyWebApi();\n```\n\nIf you have an access token, you can set it doing:\n\n```js\nspotifyApi.setAccessToken('\u003chere_your_access_token\u003e');\n```\n\nWhen you set an access token, it will be used for signing your requests. An access token is required for all endpoints.\n\nIf you want to use a Promises/A+ library, you can set it:\n\n```js\nspotifyApi.setPromiseImplementation(Q);\n```\n\nHere you see how to get basic information using a function like `getArtistAlbums`:\n\n```js\n// get Elvis' albums, passing a callback. When a callback is passed, no Promise is returned\nspotifyApi.getArtistAlbums('43ZHCT0cAZBISjO8DG9PnE', function (err, data) {\n  if (err) console.error(err);\n  else console.log('Artist albums', data);\n});\n\n// get Elvis' albums, using Promises through Promise, Q or when\nspotifyApi.getArtistAlbums('43ZHCT0cAZBISjO8DG9PnE').then(\n  function (data) {\n    console.log('Artist albums', data);\n  },\n  function (err) {\n    console.error(err);\n  }\n);\n```\n\nThe promises also expose an `abort` method that aborts the XMLHttpRequest. This is useful to cancel\nrequests that were made earlier and could be resolved out-of-sync:\n\n```js\nvar prev = null;\n\nfunction onUserInput(queryTerm) {\n  // abort previous request, if any\n  if (prev !== null) {\n    prev.abort();\n  }\n\n  // store the current promise in case we need to abort it\n  prev = spotifyApi.searchTracks(queryTerm, { limit: 5 });\n  prev.then(\n    function (data) {\n      // clean the promise so it doesn't call abort\n      prev = null;\n\n      // ...render list of search results...\n    },\n    function (err) {\n      console.error(err);\n    }\n  );\n}\n```\n\nThe functions that fetch data from the API support also an optional JSON object with a set of options, such as the ones regarding pagination. These options will be sent as query parameters:\n\n```js\n// passing a callback - get Elvis' albums in range [20...29]\nspotifyApi.getArtistAlbums(\n  '43ZHCT0cAZBISjO8DG9PnE',\n  { limit: 10, offset: 20 },\n  function (err, data) {\n    if (err) console.error(err);\n    else console.log('Artist albums', data);\n  }\n);\n\n// using Promises through Promise, Q or when - get Elvis' albums in range [20...29]\nspotifyApi\n  .getArtistAlbums('43ZHCT0cAZBISjO8DG9PnE', { limit: 10, offset: 20 })\n  .then(\n    function (data) {\n      console.log('Album information', data);\n    },\n    function (err) {\n      console.error(err);\n    }\n  );\n```\n\n### More examples\n\n_Note: The following examples use Promises/Q/when as the return object._\n\nHere you can see more examples of the usage of this wrapper:\n\n```js\n// get multiple albums\nspotifyApi.getAlbums(['5U4W9E5WsYb2jUQWePT8Xm', '3KyVcddATClQKIdtaap4bV']).then(\n  function (data) {\n    console.log('Albums information', data);\n  },\n  function (err) {\n    console.error(err);\n  }\n);\n\n// get an artists\nspotifyApi.getArtist('2hazSY4Ef3aB9ATXW7F5w3').then(\n  function (data) {\n    console.log('Artist information', data);\n  },\n  function (err) {\n    console.error(err);\n  }\n);\n\n// get multiple artists\nspotifyApi\n  .getArtists(['2hazSY4Ef3aB9ATXW7F5w3', '6J6yx1t3nwIDyPXk5xa7O8'])\n  .then(\n    function (data) {\n      console.log('Artists information', data);\n    },\n    function (err) {\n      console.error(err);\n    }\n  );\n\n// get albums by a certain artist\nspotifyApi.getArtistAlbums('43ZHCT0cAZBISjO8DG9PnE').then(\n  function (data) {\n    console.log('Artist albums', data);\n  },\n  function (err) {\n    console.error(err);\n  }\n);\n\n// search tracks whose name, album or artist contains 'Love'\nspotifyApi.searchTracks('Love').then(\n  function (data) {\n    console.log('Search by \"Love\"', data);\n  },\n  function (err) {\n    console.error(err);\n  }\n);\n\n// search artists whose name contains 'Love'\nspotifyApi.searchArtists('Love').then(\n  function (data) {\n    console.log('Search artists by \"Love\"', data);\n  },\n  function (err) {\n    console.error(err);\n  }\n);\n\n// search tracks whose artist's name contains 'Love'\nspotifyApi.searchTracks('artist:Love').then(\n  function (data) {\n    console.log('Search tracks by \"Love\" in the artist name', data);\n  },\n  function (err) {\n    console.error(err);\n  }\n);\n```\n\n### Nesting calls\n\nWhen you need to make multiple calls to get some dataset, you can take advantage of the Promises to get a cleaner code:\n\n```js\n// track detail information for album tracks\nspotifyApi\n  .getAlbum('5U4W9E5WsYb2jUQWePT8Xm')\n  .then(function (data) {\n    return data.tracks.map(function (t) {\n      return t.id;\n    });\n  })\n  .then(function (trackIds) {\n    return spotifyApi.getTracks(trackIds);\n  })\n  .then(function (tracksInfo) {\n    console.log(tracksInfo);\n  })\n  .catch(function (error) {\n    console.error(error);\n  });\n\n// album detail for the first 10 Elvis' albums\nspotifyApi\n  .getArtistAlbums('43ZHCT0cAZBISjO8DG9PnE', { limit: 10 })\n  .then(function (data) {\n    return data.albums.map(function (a) {\n      return a.id;\n    });\n  })\n  .then(function (albums) {\n    return spotifyApi.getAlbums(albums);\n  })\n  .then(function (data) {\n    console.log(data);\n  });\n```\n\n### Getting user's information\n\nIn order to get user's information you need to request a user-signed access token, from either the Implicit Grant or Authorization Code flow. Say for instance you want to get user's playlists. Once you get an access token, set it and fetch the data:\n\n```js\n// get an access token\n...\n\n// set it in the wrapper\nvar spotifyApi = new SpotifyWebApi();\nspotifyApi.setAccessToken('\u003chere_your_access_token\u003e');\nspotifyApi.getUserPlaylists('jmperezperez')\n  .then(function(data) {\n    console.log('User playlists', data);\n  }, function(err) {\n    console.error(err);\n  });\n\nspotifyApi.getPlaylist('4vHIKV7j4QcZwgzGQcZg1x')\n  .then(function(data) {\n    console.log('User playlist', data);\n  }, function(err) {\n    console.error(err);\n  });\n```\n\nSome functions don't need to receive the user's id as a parameter, and will use the\nuser's information from the access token:\n\n```js\nvar spotifyApi = new SpotifyWebApi();\nspotifyApi.setAccessToken('\u003chere_your_access_token\u003e');\nspotifyApi\n  .getUserPlaylists() // note that we don't pass a user id\n  .then(\n    function (data) {\n      console.log('User playlists', data);\n    },\n    function (err) {\n      console.error(err);\n    }\n  );\n```\n\n## Integrated Typescript Typings\n\nGet great code completion for this package using the integrated typescript typings. It includes the complete typings of the Spotify Web Api too, so you'll know both how to the navigate the API as well as the response you are getting.\n\n![Typings Example](https://raw.githubusercontent.com/JMPerez/spotify-web-api-js/master/typings-example.gif)\n\n### When bundling the library\n\nIf you are bundling spotify-web-api-js using e.g. webpack you can include the library and the typings into a typescript file like this:\n\n```typescript\nimport SpotifyWebApi from 'spotify-web-api-js';\n\nlet spotify = new SpotifyWebApi();\n```\n\n### When using the library globally\n\nIf you are using the library globally, for example including directly from index.html, include the typings in the top of your typescript file. Typescript will then assume the library is already present globally. Adjust the path to `node_modules`.\n\n```typescript\n/// \u003creference path=\"../node_modules/spotify-web-api-js/src/typings/spotify-web-api.d.ts\" /\u003e\n\nlet spotify = new SpotifyWebApi();\n```\n\n## Running tests\n\nIn order to run the tests, run:\n\n    $ npm test\n\nIf you want to check out the coverage, run:\n\n    $ npm run test:coverage\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjmperez%2Fspotify-web-api-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjmperez%2Fspotify-web-api-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjmperez%2Fspotify-web-api-js/lists"}