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

Install the package using npm:

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

Configure the Spotify client with your API credentials:

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 API Documentation: ZiloData API Docs :::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

The explore module provides search and suggestion functionality for discovering Spotify content.

Search

Search for tracks, artists, albums, playlists, podcasts, and more on Spotify. Method: client.explore.search() Parameters:

Parameter	Type	Required	Description
`keyword`	`string`	Yes	Search keyword
`offset`	`number`	No	Offset for pagination (default: 0)
`limit`	`number`	No	Number of results (1-100, default: 20)
`filterBy`	`"song" \| "playlist" \| "album" \| "artist" \| "podcast_show" \| "profile" \| "genres_mood"`	No	Type of search (default: “song”)

Example:

await client.explore.search({
  keyword: "despacito",
  offset: 0, // Optional: Offset for pagination
  limit: 20, // Optional: Number of results (1-100, default: 20)
  filterBy: "song", // 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 a keyword to help users discover related content. Method: client.explore.suggestions() Parameters:

Parameter	Type	Required	Description
`keyword`	`string`	Yes	Search keyword

Example:

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

The artists module provides comprehensive access to artist information, discography, related artists, and more.

Get Overview

Get overview information about a specific artist including profile details, statistics, and metadata. Method: client.artists.getOverview() Parameters:

Parameter	Type	Required	Description
`uri`	`string`	Yes	Spotify artist URI

Example:

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

Get Playlists

Get playlists created by or associated with the artist. Method: client.artists.getPlaylists() Parameters:

Parameter	Type	Required	Description
`uri`	`string`	Yes	Spotify artist URI

Example:

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

Get Albums

Get albums for the specified artist with pagination and sorting options. Method: client.artists.getAlbums() Parameters:

Parameter	Type	Required	Description
`uri`	`string`	Yes	Spotify artist URI
`offset`	`number`	No	Offset for pagination (default: 0)
`limit`	`number`	No	Number of results (1-100, default: 20)
`order_by`	`"DATE_DESC" \| "DATE_ASC"`	No	Order by date (default: “DATE_DESC”)

Example:

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", // Optional: Order by date (default: "DATE_DESC")
});

Get Singles

Get singles released by the specified artist. Method: client.artists.getSingles() Parameters:

Parameter	Type	Required	Description
`uri`	`string`	Yes	Spotify artist URI
`offset`	`number`	No	Offset for pagination (default: 0)
`limit`	`number`	No	Number of results (1-100, default: 20)
`order_by`	`"DATE_DESC" \| "DATE_ASC"`	No	Order by date (default: “DATE_DESC”)

Example:

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

Get Compilations

Get compilation albums featuring the specified artist. Method: client.artists.getCompilations() Parameters:

Parameter	Type	Required	Description
`uri`	`string`	Yes	Spotify artist URI
`offset`	`number`	No	Offset for pagination (default: 0)
`limit`	`number`	No	Number of results (1-100, default: 20)
`order_by`	`"DATE_DESC" \| "DATE_ASC"`	No	Order by date (default: “DATE_DESC”)

Example:

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

Get artists related to the specified artist based on listening patterns and music similarity. Method: client.artists.getRelated() Parameters:

Parameter	Type	Required	Description
`uri`	`string`	Yes	Spotify artist URI

Example:

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

Get Appears On

Get albums that the artist appears on but did not release as the primary artist. Method: client.artists.getAppearsOn() Parameters:

Parameter	Type	Required	Description
`uri`	`string`	Yes	Spotify artist URI

Example:

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

Get Featuring

Get artists that have featured this artist in their tracks. Method: client.artists.getFeaturing() Parameters:

Parameter	Type	Required	Description
`uri`	`string`	Yes	Spotify artist URI

Example:

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

Get Discovered On

Get playlists where the artist is commonly discovered by listeners. Method: client.artists.getDiscoveredOn() Parameters:

Parameter	Type	Required	Description
`uri`	`string`	Yes	Spotify artist URI

Example:

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

Get Concerts

Get concert and tour information for the artist. Method: client.artists.getConcerts() Parameters:

Parameter	Type	Required	Description
`uri`	`string`	Yes	Spotify artist URI

Example:

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

Get Discography Overview

Get a comprehensive discography overview for the artist including all releases organized by type. Method: client.artists.getDiscographyOverview() Parameters:

Parameter	Type	Required	Description
`uri`	`string`	Yes	Spotify artist URI

Example:

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

Albums Module

The albums module provides access to album details and track listings.

Get Detail

Get detailed information about an album including metadata, artists, release date, and cover art. Method: client.albums.getDetail() Parameters:

Parameter	Type	Required	Description
`uri`	`string`	Yes	Spotify album URI

Example:

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 all tracks from an album with pagination support. Method: client.albums.getTracks() Parameters:

Parameter	Type	Required	Description
`uri`	`string`	Yes	Spotify album URI
`offset`	`number`	No	Offset for pagination (default: 0)
`limit`	`number`	No	Number of results (default: 300)

Example:

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

The tracks module provides access to track details, lyrics, and recommendations.

Get Detail

Get detailed information about a track including metadata, artists, album, and duration. Method: client.tracks.getDetail() Parameters:

Parameter	Type	Required	Description
`uri`	`string`	Yes	Spotify track URI

Example:

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 if available. Method: client.tracks.getLyrics() Parameters:

Parameter	Type	Required	Description
`uri`	`string`	Yes	Spotify track URI

Example:

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

Get Recommendations

Get track recommendations based on a specific track using Spotify’s recommendation algorithm. Method: client.tracks.getRecommendations() Parameters:

Parameter	Type	Required	Description
`uri`	`string`	Yes	Spotify track URI
`limit`	`number`	No	Number of recommendations (default: 20)

Example:

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

Playlists Module

The playlists module provides access to playlist details and track listings.

Get Detail

Get detailed information about a playlist including metadata, owner, description, and follower count. Method: client.playlists.getDetail() Parameters:

Parameter	Type	Required	Description
`uri`	`string`	Yes	Spotify playlist URI

Example:

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

Get Tracks

Get all tracks from a playlist with pagination support. Method: client.playlists.getTracks() Parameters:

Parameter	Type	Required	Description
`uri`	`string`	Yes	Spotify playlist URI
`offset`	`number`	No	Offset for pagination (default: 0)
`limit`	`number`	No	Number of results (default: 300)

Example:

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

The podcasts module provides access to podcast show details and episode listings.

Get Detail

Get detailed information about a podcast show including metadata, description, and publisher information. Method: client.podcasts.getDetail() Parameters:

Parameter	Type	Required	Description
`uri`	`string`	Yes	Spotify podcast URI

Example:

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

Get Episodes

Get episodes from a podcast show with pagination support. Method: client.podcasts.getEpisodes() Parameters:

Parameter	Type	Required	Description
`uri`	`string`	Yes	Spotify podcast URI
`offset`	`number`	No	Offset for pagination (default: 0)
`limit`	`number`	No	Number of results (1-300, default: 50)

Example:

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

The users module provides access to user profile information, followers, and following lists.

Get Profile

Get user profile information including display name, followers count, and profile image. Method: client.users.getProfile() Parameters:

Parameter	Type	Required	Description
`uri`	`string`	Yes	Spotify user URI

Example:

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

Get Followers

Get list of users following the specified user. Method: client.users.getFollowers() Parameters:

Parameter	Type	Required	Description
`uri`	`string`	Yes	Spotify user URI

Example:

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

Get Following

Get list of users that the specified user is following. Method: client.users.getFollowing() Parameters:

Parameter	Type	Required	Description
`uri`	`string`	Yes	Spotify user URI

Example:

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

Error Handling

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

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);
  }
}

​Spotify API Client

​Installation

​Quick Start

​Configuration

​API Structure

​API Reference

​Explore Module

​Search

​Suggestions

​Artists Module

​Get Overview

​Get Playlists

​Get Albums

​Get Singles

​Get Compilations

​Get Related

​Get Appears On

​Get Featuring

​Get Discovered On

​Get Concerts

​Get Discography Overview

​Albums Module

​Get Detail

​Get Tracks

​Tracks Module

​Get Detail

​Get Lyrics

​Get Recommendations

​Playlists Module

​Get Detail

​Get Tracks

​Podcasts Module

​Get Detail

​Get Episodes

​Users Module

​Get Profile

​Get Followers

​Get Following

​Error Handling

​Additional Resources

Spotify API Client

Installation

Quick Start

Configuration

API Structure

API Reference

Explore Module

Search

Suggestions

Artists Module

Get Overview

Get Playlists

Get Albums

Get Singles

Get Compilations

Get Related

Get Appears On

Get Featuring

Get Discovered On

Get Concerts

Get Discography Overview

Albums Module

Get Detail

Get Tracks

Tracks Module

Get Detail

Get Lyrics

Get Recommendations

Playlists Module

Get Detail

Get Tracks

Podcasts Module

Get Detail

Get Episodes

Users Module

Get Profile

Get Followers

Get Following

Error Handling

Additional Resources