> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zilodata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Spotify SDK

> Complete guide to Spotify API SDK for TypeScript. Learn how to search tracks, get artist details, fetch album information, access playlists, podcasts, and user data with the @msp67/spotify-api client library.

# 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:

```bash theme={null}
npm install @msp67/spotify-api
```

## Quick Start

```typescript theme={null}
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:

```typescript theme={null}
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](https://rapidapi.com/zilodata12-zilodata-default/api/spotify-api31)

**API Documentation:** [ZiloData API Docs](/api-reference/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

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:**

```typescript theme={null}
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:**

```json theme={null}
{
  "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:**

```typescript theme={null}
await client.explore.suggestions({
  keyword: "despati",
});
```

**Example Response:**

```json theme={null}
{
  "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:**

```typescript theme={null}
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:**

```typescript theme={null}
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:**

```typescript theme={null}
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:**

```typescript theme={null}
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:**

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

#### Get Related

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:**

```typescript theme={null}
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:**

```typescript theme={null}
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:**

```typescript theme={null}
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:**

```typescript theme={null}
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:**

```typescript theme={null}
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:**

```typescript theme={null}
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:**

```typescript theme={null}
await client.albums.getDetail({
  uri: "spotify:album:3Gq2Dme9nesdgoqNNlcN8O",
});
```

**Example Response:**

```json theme={null}
{
  "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:**

```typescript theme={null}
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:**

```typescript theme={null}
await client.tracks.getDetail({
  uri: "spotify:track:4WNcduiCmDNfmTEz7JvmLv",
});
```

**Example Response:**

```json theme={null}
{
  "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:**

```typescript theme={null}
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:**

```typescript theme={null}
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:**

```typescript theme={null}
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:**

```typescript theme={null}
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:**

```typescript theme={null}
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:**

```typescript theme={null}
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:**

```typescript theme={null}
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:**

```typescript theme={null}
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:**

```typescript theme={null}
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:

```typescript theme={null}
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);
  }
}
```

## Additional Resources

* [Spotify API Documentation](/api-reference/spotify-api)
* [Get API Key on RapidAPI](https://rapidapi.com/zilodata12-zilodata-default/api/spotify-api31)
* [SDKs Overview](/api-reference/sdks)