Search Spotify Resources

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

We'll cover the following

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.

The Search for Item 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 the search query term that 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 them using a comma (,).

include_external

Optional

String

This decides whether the user can play an externally hosted audio or not. The only possible value for this parameter 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.

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
const endpointUrl = new URL('https://api.spotify.com/v1/search');
const queryParameters = new URLSearchParams({
  q: 'metallica',
  type: 'artist'
});
headerParameters = {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer {{CLIENT_CREDENTIALS_ACCESS_TOKEN}}'
}
const options = {
  method: 'GET',
  headers: headerParameters
};
async function searchArtist() {
  try {
    endpointUrl.search = queryParameters;
    const response = await fetch(endpointUrl, options);
    printResponse(response);
  } 
  catch (error) {
    printError(error);
  }
}
searchArtist();

Let's look at a brief explanation of the code above:

  • Line 1: We set the URL to https://api.spotify.com/v1/search.

  • Lines 3–6: We update the query parameters.

  • Line 13: We set the request type to GET.

  • Lines 17–27: We define a function, searchArtist(). This function calls the API and prints the response.

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

Press + to interact
const endpointUrl = new URL('https://api.spotify.com/v1/search');
const queryParameters = new URLSearchParams({
  q: 'metallica',
  type: 'artist'
});
headerParameters = {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer {{AUTHORIZATION_CODE_ACCESS_TOKEN}}'
}
const options = {
  method: 'GET',
  headers: headerParameters
};
async function fetchAsteroidsData() {
  try {
    endpointUrl.search = queryParameters;
    const response = await fetch(endpointUrl, options);
    printResponse(response);
  } 
  catch (error) {
    printError(error);
  }
}
fetchAsteroidsData();

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.

We made the following changes in the code:

  • Line 9: We replace the client credentials access token with the authorization code access token.

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.

We can also change the query parameters to filter the results as per our needs. Try changing the type (in line 5) and notice the change in the response fields.

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

Object [array]

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.