Search Spotify Resources

Learn how to search for information about an artist, playlist, album, show, or an episode.

We'll cover the following

Overview

Now that we have the authorization token, we can start exploring the endpoints of the Spotify API. The first endpoint in our list is the Search for Item endpoint.

This endpoint provides us the option to search for information about any artist, album, track, show, or episode. The base URI used for this endpoint is https://api.spotify.com/v1/search. It returns us the information available on Spotify. This endpoint provides the Spotify IDs that can be used with other endpoints requiring a Spotify ID.

Request parameters

The query parameters for the Search for Item endpoint are given in the table below:

Query parameter

Category

Type

Description

q

Required

String

This is set to what we want to search using this endpoint.

type

Required

String

This is the category we want to search in. The possible options are: album, artist, playlist, track, show, episode. We can also use multiple categories by separating the using a comma(,).

include_external

Optional

String

This decides whether the user can play externally hosted audio or not. Its possible option is audio, which allows the user to play externally hosted audio. By default, the user is not allowed to do so.

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.

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 parameter can be used to offset the first item we get in response.

Search for an artist using client credentials access token

The items we get in response differ based on whether we use the client credentials access token or authorization code access token for this endpoint. The code below calls this endpoint with the client credentials access token. Click the "Run" button to see the response.

Note: If the client credential access token has expired, refer to this lesson in the "Appendix" chapter to refresh the access token.

Press + to interact
url = ('https://api.spotify.com/v1/search?'
       'q=metallica&'
       'type=artist')
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))
  • Lines 1–3: We define the URL.
  • Lines 5–8: We define the header.
  • Line 10: We make the API call and save the JSON response in the response variable.
  • Line 11: We print the response.

Note: The code structure will remain the same for all other endpoints. We only need to change the URLs and the request type (for some endpoints).

Search for an artist using an authorization code access token

Let's replace the client credentials access token in line 7 of our code with the authorization code access token to see how changing the tokens affects the response.

Press + to interact
url = ('https://api.spotify.com/v1/search?'
       'q=jake&'
       'type=artist')
headers = {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer {{AUTHORIZATION_CODE_ACCESS_TOKEN}}'
}
response = requests.request("GET", url, headers=headers)
print(json.dumps(response.json(), indent=4))

Note: If your authorization code access token has expired, you can refresh the access token using the code in this lesson of the "Appendix" chapter.

Notice that this time the output result is different from the previous executable. Because now, the results are filtered based on the country associated with our profile. So the authorization code access token can also affect the results of some public endpoints.

Response fields

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

Response field

Type

Description

genres

String

This array contains the genres the artist has performed in.

name

String

This is the name of the artist.

popularity

Integer

This index shows how popular an artist is on Spotify. It ranges from 0 to 100 with 100 being the most popular.

images

Array of objects

This contains the information for the artist's images. Each object in this array contains three elements which give us the URL, height, and width of the image respectively.

id

String

This is the Spotify ID of the artist.

next

String

This is the link to the next page.

previous

String

This is the link to the previous page.

total

Integer

This tells us the total number of albums that we get in response.

Try changing the type (in line 3) and notice the change in the response fields.