Spotify API Client

A TypeScript client library for the Spotify API. This library provides easy access to Spotify search, artists, albums, tracks, playlists, podcasts, and users APIs.

Installation

npm install @msp67/spotify-api

Quick Start

import { SpotifyClient } from "@msp67/spotify-api";

// Initialize the client with your API key
// Get your API key from: https://rapidapi.com/zilodata12-zilodata-default/api/spotify-api31
const client = new SpotifyClient({
  apiKey: "your-api-key-here",
});

// Search for tracks
const searchResults = await client.explore.search({
  keyword: "despacito",
  filterBy: "song",
});

// Get artist overview
const artistInfo = await client.artists.getOverview({
  uri: "spotify:artist:4GLJPBj5Cdr9AgLKvLWM4n",
});

// Get track details
const trackDetails = await client.tracks.getDetail({
  uri: "spotify:track:6habFhsOp2NvshLv26DqMb",
});

Configuration

const client = new SpotifyClient({
  apiKey: "your-api-key", // Required: Your API subscription key
  timeout: 30000, // Optional: Request timeout in milliseconds (default: 30000)
});

Get your API key: RapidAPI - Spotify API

Note: The API endpoint is hardcoded and cannot be changed.

API Structure

The library is organized into modules, each providing specific functionality:

SpotifyClient
│
├── explore
│   ├── search(keyword, offset?, limit?, filterBy?)
│   └── suggestions(keyword)
│
├── artists
│   ├── getOverview(uri)
│   ├── getPlaylists(uri)
│   ├── getAlbums(uri, offset?, limit?, order_by?)
│   ├── getSingles(uri, offset?, limit?, order_by?)
│   ├── getCompilations(uri, offset?, limit?, order_by?)
│   ├── getRelated(uri)
│   ├── getAppearsOn(uri)
│   ├── getFeaturing(uri)
│   ├── getDiscoveredOn(uri)
│   ├── getConcerts(uri)
│   └── getDiscographyOverview(uri)
│
├── albums
│   ├── getDetail(uri)
│   └── getTracks(uri, offset?, limit?)
│
├── tracks
│   ├── getDetail(uri)
│   ├── getLyrics(uri)
│   └── getRecommendations(uri, limit?)
│
├── playlists
│   ├── getDetail(uri)
│   └── getTracks(uri, offset?, limit?)
│
├── podcasts
│   ├── getDetail(uri)
│   └── getEpisodes(uri, offset?, limit?)
│
└── users
    ├── getProfile(uri)
    ├── getFollowers(uri)
    └── getFollowing(uri)

• ? = Optional parameter

API Reference

Explore Module

Search

Search for tracks, artists, albums, playlists, etc.

await client.explore.search({
  keyword: "despacito",
  offset: 0, // Optional: Offset for pagination
  limit: 20, // Optional: Number of results (1-100, default: 20)
  filterBy:
    "song" |
    "playlist" |
    "album" |
    "artist" |
    "podcast_show" |
    "profile" |
    "genres_mood", // Optional: Type of search (default: "song")
});

Example Response:

{
  "message": "Success",
  "statusCode": 200,
  "data": [
    {
      "id": "6habFhsOp2NvshLv26DqMb",
      "name": "Despacito",
      "uri": "spotify:track:6habFhsOp2NvshLv26DqMb",
      "duration": 229360,
      "artists": [
        {
          "name": "Luis Fonsi",
          "uri": "spotify:artist:4V8Sr092TqfHkfAA5fXXqG"
        }
      ],
      "album": {
        "id": "5C0YLr4OoRGFDaqdMQmkeH",
        "name": "VIDA",
        "uri": "spotify:album:5C0YLr4OoRGFDaqdMQmkeH",
        "coverArt": [
          {
            "url": "https://i.scdn.co/image/ab67616d00001e02ef0d4234e1a645740f77d59c",
            "width": 300,
            "height": 300
          }
        ]
      }
    }
  ]
}

Suggestions

Get search suggestions based on keyword.

await client.explore.suggestions({
  keyword: "despati",
});

Example Response:

{
  "message": "Success",
  "statusCode": 200,
  "data": {
    "suggestions": [
      {
        "type": "text",
        "suggestion": "despacito justin bieber",
        "uri": "spotify:search:despacito+justin+bieber"
      },
      {
        "type": "track",
        "id": "6habFhsOp2NvshLv26DqMb",
        "name": "Despacito",
        "uri": "spotify:track:6habFhsOp2NvshLv26DqMb",
        "duration": 229360,
        "artists": [
          {
            "name": "Luis Fonsi",
            "uri": "spotify:artist:4V8Sr092TqfHkfAA5fXXqG"
          }
        ]
      }
    ]
  }
}

Artists Module

Get Overview

Get overview information about a specific artist.

await client.artists.getOverview({
  uri: "spotify:artist:41MozSoPIsD1dJM0CLPjZF",
});

Get Playlists

Get playlists created by or associated with the artist.

await client.artists.getPlaylists({
  uri: "spotify:artist:4GLJPBj5Cdr9AgLKvLWM4n",
});

Get Albums

Get albums for the specified artist.

await client.artists.getAlbums({
  uri: "spotify:artist:1yxSLGMDHlW21z4YXirZDS",
  offset: 0, // Optional: Offset for pagination (default: 0)
  limit: 20, // Optional: Number of results (1-100, default: 20)
  order_by: "DATE_DESC" | "DATE_ASC", // Optional: Order by date (default: "DATE_DESC")
});

Get Singles

Get singles for the specified artist.

await client.artists.getSingles({
  uri: "spotify:artist:1yxSLGMDHlW21z4YXirZDS",
  offset: 0,
  limit: 20,
  order_by: "DATE_DESC",
});

Get Compilations

Get compilations for the specified artist.

await client.artists.getCompilations({
  uri: "spotify:artist:1yxSLGMDHlW21z4YXirZDS",
  offset: 0,
  limit: 20,
  order_by: "DATE_DESC",
});

Get Related

Get related artists.

await client.artists.getRelated({
  uri: "spotify:artist:41MozSoPIsD1dJM0CLPjZF",
});

Get Appears On

Get albums that the artist appears on.

await client.artists.getAppearsOn({
  uri: "spotify:artist:41MozSoPIsD1dJM0CLPjZF",
});

Get Featuring

Get artists featuring this artist.

await client.artists.getFeaturing({
  uri: "spotify:artist:41MozSoPIsD1dJM0CLPjZF",
});

Get Discovered On

Get playlists where the artist is discovered.

await client.artists.getDiscoveredOn({
  uri: "spotify:artist:41MozSoPIsD1dJM0CLPjZF",
});

Get Concerts

Get concerts for the artist.

await client.artists.getConcerts({
  uri: "spotify:artist:41MozSoPIsD1dJM0CLPjZF",
});

Get Discography Overview

Get discography overview for the artist.

await client.artists.getDiscographyOverview({
  uri: "spotify:artist:41MozSoPIsD1dJM0CLPjZF",
});

Albums Module

Get Detail

Get detailed information about an album.

await client.albums.getDetail({
  uri: "spotify:album:3Gq2Dme9nesdgoqNNlcN8O",
});

Example Response:

{
  "message": "Success",
  "statusCode": 200,
  "data": {
    "id": "3Gq2Dme9nesdgoqNNlcN8O",
    "name": "Despacito Feat. Justin Bieber (Remix)",
    "uri": "spotify:album:3Gq2Dme9nesdgoqNNlcN8O",
    "artists": [
      {
        "id": "4V8Sr092TqfHkfAA5fXXqG",
        "name": "Luis Fonsi",
        "uri": "spotify:artist:4V8Sr092TqfHkfAA5fXXqG"
      }
    ],
    "coverArt": [
      {
        "url": "https://i.scdn.co/image/ab67616d00001e02a6a335d613d151c626895a83",
        "width": 300,
        "height": 300
      }
    ],
    "date": {
      "isoString": "2017-04-17T00:00:00Z",
      "precision": "DAY",
      "year": 2017
    },
    "type": "SINGLE",
    "totalTracks": 1
  }
}

Get Tracks

Get tracks from an album.

await client.albums.getTracks({
  uri: "spotify:album:3Gq2Dme9nesdgoqNNlcN8O",
  offset: 0, // Optional: Offset for pagination (default: 0)
  limit: 300, // Optional: Number of results (default: 300)
});

Tracks Module

Get Detail

Get detailed information about a track.

await client.tracks.getDetail({
  uri: "spotify:track:4WNcduiCmDNfmTEz7JvmLv",
});

Example Response:

{
  "message": "Success",
  "statusCode": 200,
  "data": {
    "id": "4WNcduiCmDNfmTEz7JvmLv",
    "name": "In Control (feat. Selin)",
    "uri": "spotify:track:4WNcduiCmDNfmTEz7JvmLv",
    "duration": {
      "totalMilliseconds": 179232
    },
    "artists": [
      {
        "id": "3t8WiyalpvnB9AObcMufiE",
        "name": "Mahmut Orhan",
        "uri": "spotify:artist:3t8WiyalpvnB9AObcMufiE"
      }
    ],
    "album": {
      "id": "1B68g8b4wpedNDvvQLAoCe",
      "name": "In Control (feat. Selin)",
      "uri": "spotify:album:1B68g8b4wpedNDvvQLAoCe",
      "type": "SINGLE"
    }
  }
}

Get Lyrics

Get lyrics for a track.

await client.tracks.getLyrics({
  uri: "spotify:track:4WNcduiCmDNfmTEz7JvmLv",
});

Get Recommendations

Get track recommendations based on a track.

await client.tracks.getRecommendations({
  uri: "spotify:track:4WNcduiCmDNfmTEz7JvmLv",
  limit: 20, // Optional: Number of recommendations (default: 20)
});

Playlists Module

Get Detail

Get detailed information about a playlist.

await client.playlists.getDetail({
  uri: "spotify:playlist:37i9dQZF1DXcBWIGoYBM5M",
});

Get Tracks

Get tracks from a playlist.

await client.playlists.getTracks({
  uri: "spotify:playlist:37i9dQZF1DXcBWIGoYBM5M",
  offset: 0, // Optional: Offset for pagination (default: 0)
  limit: 300, // Optional: Number of results (default: 300)
});

Podcasts Module

Get Detail

Get detailed information about a podcast.

await client.podcasts.getDetail({
  uri: "spotify:show:7FevBPboXDSB4K90BJ54pA",
});

Get Episodes

Get episodes from a podcast.

await client.podcasts.getEpisodes({
  uri: "spotify:show:7FevBPboXDSB4K90BJ54pA",
  offset: 0, // Optional: Offset for pagination (default: 0)
  limit: 50, // Optional: Number of results (1-300, default: 50)
});

Users Module

Get Profile

Get user profile information.

await client.users.getProfile({
  uri: "spotify:user:3a21dhehyczbkbq2w3gx1nsd3",
});

Get Followers

Get user followers.

await client.users.getFollowers({
  uri: "spotify:user:3a21dhehyczbkbq2w3gx1nsd3",
});

Get Following

Get users that this user is following.

await client.users.getFollowing({
  uri: "spotify:user:3a21dhehyczbkbq2w3gx1nsd3",
});

Error Handling

The client uses axios for HTTP requests. Errors will be thrown as axios errors:

try {
  const result = await client.explore.search({ keyword: "test" });
} catch (error) {
  if (error.response) {
    // The request was made and the server responded with a status code
    // that falls out of the range of 2xx
    console.error("Error status:", error.response.status);
    console.error("Error data:", error.response.data);
  } else if (error.request) {
    // The request was made but no response was received
    console.error("No response received");
  } else {
    // Something happened in setting up the request
    console.error("Error:", error.message);
  }
}

License

MIT