Featured Playlists and Playlist Items

Learn how to get information about featured playlists and view the items of a playlist using Spotify API.

We'll cover the following

Overview

In this lesson, we'll discuss the following two endpoints:

  • Get Featured Playlists
  • Add Items to Playlist

Most popular playlists

​​Featured playlists are the most popular playlists among Spotify users. We can get a list of these playlists using the Get Featured Playlists endpoint. The base URI of this endpoint is https://api.spotify.com/v1/browse/featured-playlists.

Request parameters

The table below contains information about the query parameters for this endpoint.

Query parameter

Category

Type

Description

limit

Optional

Integer

This limits the number of items to be returned in the response. Its value ranges from 0 to 50 and the default value is 20.

country

Optional

String

This is an ISO 3166-1 alpha-2 country code that we can use to fetch only the content available in a specific country. Some examples of country codes are us for the United States, es for Spain, and fr for France.

locale

Optional

String

This is used when we want the results to be in a specific language. Its value consists of a lowercase ISO language code and an uppercase ISO country code combined together using an underscore(_). For example, if we want the results in Spanish, our value will be es_ES. 

offset

Optional

Integer

This parameter can be used to offset the first item we get in response.

timestamp

Optional

String

We can use this parameter to get results for a specific date and time in the day. Its format is yyyy-MM-ddTHH:mm:ss. Its default value is the current UTC time.

Get a list of featured playlists on Spotify

The code below shows how to get a list of featured playlists on Spotify. Click the "Run" button to get the list.

Press + to interact
url = 'https://api.spotify.com/v1/browse/featured-playlists'
headers = {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer {{CLIENT_CREDENTIALS_ACCESS_TOKEN}}'
}
response = requests.request("GET", url, headers=headers)
print(json.dumps(response.json(), indent=4))

We can filter this list using the query parameters. For example, if we want the playlists featured in Spain on Spotify, we'll add ?country=ES after the base URI in line 1. Similarly, we can use other query parameters to get the kind of list that we want.

We're extracting the id of the first playlist in response to use it with the second endpoint.

Response fields

Some important response fields of the code above are given below:

Response field

Type

Description

description

String

This is the description of the playlist written by its owner.

owner

Array of objects

This contains information about the owner of the playlist.

tracks

Array of objects

This contains information about the tracks in the playlist.

images

Array of objects

This contains the link for the cover image of the playlist and its dimensions.

id

String

This is the ID of the playlist.

name

String

This is the name of the playlist.

Playlist items

Each playlist has its number of tracks which we get in response to the API call to the endpoint we discussed above. We can get more information about these tracks using the Playlist Items endpoint. The base URL for this endpoint is https://api.spotify.com/v1/playlists/{id}/tracks. The path parameter {id} will be replaced with the playlist ID when we want to make an API call. Let's assume that we want to fetch a playlist with Spotify ID sample_id. Our URL, in this case, will be https://api.spotify.com/v1/artists/sample_id.

Request parameters

The information obtained by calling this endpoint can be filtered using the following query parameters.

Query parameter

Category

Type

Description

additional_types

Optional

String

This contains the types of items, separated by a comma, that the user supports. Its possible values are tracks and episodes. Its default value is tracks.

fields

Optional

String

This contains the list of fields that the user wants in response, separated by a comma.

limit

Optional

Integer

This limits the number of items we get in response. Its value ranges from 0 to 50. Its default value is 20.

market

Optional

String

This is an ISO 3166-1 alpha-2 country code that we can use to fetch only the content available in a specific country. Some examples of country codes are us for the United States, es for Spain, and fr for France. If we send an auth code access token in the request header, the user's country will take priority over the country specified in this parameter.

offset

Optional

Integer

This is the index of the first item we'll get in response. Its default value is 0.

Retrieve playlist items

Let's see how we can use this endpoint to get the information about items in a playlist.

Press + to interact
url = 'https://api.spotify.com/v1/playlists/{{PLAYLIST_ID}}/tracks'
headers = {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer {{CLIENT_CREDENTIALS_ACCESS_TOKEN}}'
}
response = requests.request("GET", url, headers=headers)
print(json.dumps(response.json(), indent=4))

Try changing the playlist ID in line 1 to get information about items from a different playlist.

Response fields

The response of this endpoint contains the following information:

Response field

Type

Description

album

Array of objects

This contains the information about the album of the track.

episode

Boolen

This tells us if an episode on this track exists or not.

name

String

This is the name of the track.

popularity

Integer

This index shows how popular a track is. Its value ranges from 0 to 100 with 100 being the most popular.

preview_url

String

This is the URL to a 30 seconds preview of the track.

artists

Array of objects

This contains information about the artists who performed in this track.

duration_ms

Integer

This is the duration of the track in milliseconds.

id

String

This is the Spotify ID of the track.

available_markets

Array of objects

This is the list of markets in which this track is available.