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

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

$3

#### 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"
}
]
}
]
}
}
`

$3

#### 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",
});
`

$3

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

$3

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

$3

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

$3

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

$3

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