npm package: @msp67/spotify-api
Description: Spotify API client - Search, Artists, Albums, Tracks, Playlists, Podcasts, and Users APIs
Latest version: 1.0.2

# 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

```bash
npm install @msp67/spotify-api
```

## Quick Start

```typescript
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

```typescript
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)

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

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

```json
{
  "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.

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

**Example Response:**

```json
{
  "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.

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

#### Get Playlists

Get playlists created by or associated with the artist.

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

#### Get Albums

Get albums for the specified artist.

```typescript
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.

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

#### Get Compilations

Get compilations for the specified artist.

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

#### Get Related

Get related artists.

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

#### Get Appears On

Get albums that the artist appears on.

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

#### Get Featuring

Get artists featuring this artist.

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

#### Get Discovered On

Get playlists where the artist is discovered.

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

#### Get Concerts

Get concerts for the artist.

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

#### Get Discography Overview

Get discography overview for the artist.

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

### Albums Module

#### Get Detail

Get detailed information about an album.

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

**Example Response:**

```json
{
  "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.

```typescript
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.

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

**Example Response:**

```json
{
  "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.

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

#### Get Recommendations

Get track recommendations based on a track.

```typescript
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.

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

#### Get Tracks

Get tracks from a playlist.

```typescript
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.

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

#### Get Episodes

Get episodes from a podcast.

```typescript
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.

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

#### Get Followers

Get user followers.

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

#### Get Following

Get users that this user is following.

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

## Error Handling

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

```typescript
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