kelsny/spotify

Fast-paced and versatile Spotify API wrapper for Node.

spotifyx

Fast-paced and versatile Spotify API wrapper for Node.

Covers:

• Search API
• Browse API
• Albums API
• Artists API
• Tracks API
• Shows API
• Episodes API
• User API
• Markets API

Installation and Usage

Installation

Using NPM:

npm install --save spotifyx

Using Yarn:

yarn add spotifyx

Usage

CommonJS

const Spotify = require("spotifyx");

ES6

import Spotify from "spotifyx";

Simple Example

import Spotify from "spotifyx";

(async () => {
    const client = new Spotify({
        clientId: "a-cool-id",
        clientSecret: "a-cool-secret",
    });

    await client.login();

    console.log(await client.search("Null Magma", ["artist"]));
})();

Documentation

Key:

• 🄲 – Class declaration
• 🄿 – Property
• 🄼 – Method

Most typedefs are from Spotify's documentation.

🄲 Spotify

🄲 Spotify

Constructs a new Spotify API client.

Parameters:

• credentials – Client credentials to log in
  • clientId – Client ID
  • clientSecret – Client secret
  • redirectUrl? – URL to redirect to

Returns:

• Spotify – The newly created client

Example:

const client = new Spotify({
    clientId: "a-cool-id",
    clientSecret: "a-cool-secret",
});

---

Properties

🄿 Spotify#token

readonly string

The client's current access token

---

🄿 Spotify#browse

Browser

The client's Spotify browse API

---

🄿 Spotify#artists

Artists

The client's Spotify artists API

---

🄿 Spotify#albums

Albums

The client's Spotify albums API

---

🄿 Spotify#tracks

Tracks

The client's Spotify tracks API

---

🄿 Spotify#episodes

Episodes

The client's Spotify episodes API

---

🄿 Spotify#shows

Shows

The client's Spotify shows API

---

Methods

🄼 Spotify#login

Logs the client in and creates an access token.

Parameters:

Returns:

• string – The newly created access token

Example:

await client.login();

---

🄼 Spotify#search

Searches Spotify using Spotify's search API.

Parameters:

• query – Search query
• types – Object types to search for
• options? – Search options
  • market? – Market to search within
  • limit? – Search results limit
  • offset? – Search results offset
  • includeExternal? – Include externals in results

Returns:

• SearchResponse – Search results

Example:

const results = await client.search("Null Magma", ["artist"]);

---

🄼 Spotify#user

Obtains a user from Spotify using an ID.

Parameters:

• id – The user's ID

Returns:

• PublicUserObject? – User obtained from the user ID, or undefined if no user was found

Example:

const user = await client.user("a-cool-id");

---

🄼 Spotify#markets

Gets all the markets.

Parameters:

Returns:

• string[] – All markets

Example:

const markets = await client.markets();

🄲 Browser

🄲 Browser

Wrapper for Spotify's browse API.

private

---

Methods

🄼 Browser#newReleases

Fetches newest releases.

Parameters:

• options? – Fetch options
  • country? – Country code
  • limit? – Fetch limit
  • offset? – Fetch offset

Returns:

• BrowseNewReleasesResponse – Fetched new releases

Example:

const releases = await client.browse.newReleases({
    limit: 25,
    offset: 25,
});

---

🄼 Browser#featuredPlaylists

Fetches featured playlists.

Parameters:

• options? – Fetch options
  • country? – Country code
  • locale? – Locale
  • timestamp? – Timestamp
  • limit? – Fetch limit
  • offset? – Fetch offset

Returns:

• BrowseFeaturedPlaylistsResponse – Fetched featured playlists

Example:

const playlists = await client.browse.featuredPlaylists();

---

🄼 Browser#allCategories

Fetches all categories.

Parameters:

• options? – Fetch options
  • country? – Country code
  • locale? – Locale
  • limit? – Fetch limit
  • offset? – Fetch offset

Returns:

• BrowseAllCategoriesResponse – Fetched categories

Example:

const categories = await client.browse.allCategories();

---

🄼 Browser#category

Fetches a category.

Parameters:

• category – The category
• options? – Fetch options
  • country? – Country code
  • locale? – Locale

Returns:

• BrowseCategoryResponse – Fetched categories

Example:

const category = await client.browse.category("party");

---

🄼 Browser#categoryPlaylists

Fetches a category's playlists.

Parameters:

• category – The category
• options? – Fetch options
  • country? – Country code
• limit? – Fetch limit
• offset? – Fetch offset

Returns:

• PagingObject<SimplifiedPlaylistObject> – Fetched playlists

Example:

const playlists = await client.browse.categoryPlaylists("party");

---

🄼 Browser#recommendations

Fetches a category's playlists.

Parameters:

• seeds – Seeds
  • artists – Seed artists
  • genres – Seed genres
  • tracks - Seed tracks
• options? – Fetch options
  • Not available

Returns:

• BrowseRecommendationsResponse – Fetched category platlists

Example:

Not available

---

🄼 Browser#recommendationGenres

Fetches recommendation genres.

Parameters:

Returns:

• string[] – Fetched genres

Example:

const genres = await client.browse.recommendationGenres();

🄲 Artists

🄲 Artists

Wrapper for Spotify's artists API.

private

---

Methods

🄼 Artists#get

Retrieves an artist or multiple artists.

Parameters:

• ids – Can either be an ID or array of IDs.

Returns:

If a single ID is used:

• ArtistsSingleArtistResponse – The artist retrieved

If an array of IDs is used:

• ArtistsMultipleArtistsResponse – The artists retrieved

Example:

const artists = await client.artists.get(["a-id", "another-id"]);

---

🄼 Artists#topTracks

Retrieves an artist's top tracks.

Parameters:

• id – Artist ID

Returns:

• ArtistsTopTracksResponse – The artist's top tracks

Example:

const topTracks = await client.artists.topTracks("an-id");

---

🄼 Artists#related

Retrieves an artist's related artists.

Parameters:

• id – Artist ID

Returns:

• ArtistsRelatedArtistsResponse – The artist's related artists

Example:

const related = await client.artists.related("an-id");

---

🄼 Artists#albums

Retrieves an artist's albums.

Parameters:

• id – Artist ID

Returns:

• ArtistsAlbumsResponse – The artist's albums

Example:

const albums = await client.artists.albums("an-id");

🄲 Albums

🄲 Shows

Wrapper for Spotify's shows API.

private

---

Methods

🄼 Albums#get

Retrieves an album or multiple albums.

Parameters:

• ids – Can either be an ID or array of IDs.
• options? – Fetch options
  • market? – Country code

Returns:

If a single ID is used:

• AlbumsSingleAlbumResponse – The album retrieved

If an array of IDs is used:

• AlbumsMultipleAlbumsResponse – The albums retrieved

Example:

const albums = await client.albums.get(["an-id", "another-id"]);

---

🄼 Albums#tracks

Retrieves an album's tracks.

Parameters:

• id – The album's ID
• options? – Fetch options
  • market – Country code
  • limit – Fetch limit
  • offset – Fetch offset

Returns:

• AlbumsTracksResponse – The album's tracks

Example:

const tracks = await client.albums.tracks("an-id");

🄲 Tracks

🄲 Tracks

Wrapper for Spotify's tracks API.

private

---

Methods

🄼 Tracks#get

Retrieves a track or multiple tracks.

Parameters:

• ids – Can either be an ID or array of IDs.
• options? – Fetch options
  • market? – Country code

Returns:

If a single ID is used:

• TracksSingleTrackResponse – The track retrieved

If an array of IDs is used:

• TracksMultipleTracksResponse – The tracks retrieved

---

🄼 Tracks#audioFeatures

Retrieves a track or multiple tracks' audio features.

Parameters:

• ids – Can either be an ID or array of IDs.
• options? – Fetch options
  • market? – Country code

Returns:

If a single ID is used:

• TracksSingleTrackAudioFeatureResponse – The audio feature retrieved

If an array of IDs is used:

• TracksMultipleTracksAudioFeaturesResponse – The audio features retrieved

🄼 Tracks#audioAnalysis

Retrieves a track's audio analysis

Parameters:

• id – Track ID

Returns:

• AudioAnalysisObject – The audio analysis

🄲 Episodes

🄲 Episodes

Wrapper for Spotify's episodes API.

private

---

Methods

🄼 Episodes#get

Retrieves an episode or multiple episodes.

Parameters:

• ids – Can either be an ID or array of IDs.
• options? – Fetch options
  • market? – Country code

Returns:

If a single ID is used:

• EpisodesSingleEpisodeResponse – The episode retrieved

If an array of IDs is used:

• EpisodesMultipleEpisodesResponse – The episodes retrieved

🄲 Shows

🄲 Shows

Wrapper for Spotify's shows API.

private

---

Methods

🄼 Shows#get

Retrieves a show or multiple shows.

Parameters:

• ids – Can either be an ID or array of IDs.
• options? – Fetch options
  • market? – Country code

Returns:

If a single ID is used:

• ShowsSingleShowResponse – The show retrieved

If an array of IDs is used:

• ShowsMultipleShowsResponse – The shows retrieved

Example:

const shows = await client.shows.get(["an-id", "another-id"]);

---

🄼 Shows#episodes

Retrieves a show's episodes.

Parameters:

• id – The show's ID

Returns:

• ShowsEpisodesResponse – The episodes retrieved

Example:

const episodes = await client.shows.episodes("an-id");

Future features

• Include other three authorization flows
• Use refresh tokens
• Spotify user auth service
  • Authorization scopes
  • Access to user-related APIs
  • Access to other APIs