Web API •References / Search / Search for Item

Search for Item

Get Spotify catalog information about albums, artists, playlists, tracks, shows, episodes or audiobooks that match a keyword string.
Note: Audiobooks are only available for the US, UK, Ireland, New Zealand and Australia markets.

Important policy note

Request

q
string
Required
Your search query.

You can narrow down your search using field filters. The available filters are album, artist, track, year, upc, tag:hipster, tag:new, isrc, and genre. Each field filter only applies to certain result types.

The artist and year filters can be used while searching albums, artists and tracks. You can filter on a single year or a range (e.g. 1955-1960).
The album filter can be used while searching albums and tracks.
The genre filter can be used while searching artists and tracks.
The isrc and track filters can be used while searching tracks.
The upc, tag:new and tag:hipster filters can only be used while searching albums. The tag:new filter will return albums released in the past two weeks and tag:hipster can be used to return only albums with the lowest 10% popularity.
Example value: "remaster%20track:Doxy%20artist:Miles%20Davis"
type
array of strings
Required
A comma-separated list of item types to search across. Search results include hits from all the specified item types. For example: q=abacab&type=album,track returns both albums and tracks matching "abacab".
Allowed values: "album", "artist", "playlist", "track", "show", "episode", "audiobook"
market
string
An ISO 3166-1 alpha-2 country code. If a country code is specified, only content that is available in that market will be returned.
If a valid user access token is specified in the request header, the country associated with the user account will take priority over this parameter.
Note: If neither market or user country are provided, the content is considered unavailable for the client.
Users can view the country that is associated with their account in the account settings.
Example value: "ES"
limit
integer
The maximum number of results to return in each item type.
Example value: 10Default value: 20Range: 0 - 50
offset
integer
The index of the first result to return. Use with limit to get the next page of search results.
Example value: 5Default value: 0Range: 0 - 1000
include_external
string
If include_external=audio is specified it signals that the client can play externally hosted audio content, and marks the content as playable in the response. By default externally hosted audio content is marked as unplayable in the response.
Allowed values: "audio"

Response

Search response

- href
  string
  Required
  A link to the Web API endpoint returning the full result of the request
  Example value: "https://api.spotify.com/v1/me/shows?offset=0&limit=20"
- limit
  integer
  Required
  The maximum number of items in the response (as set in the query or by default).
  Example value: 20
- next
  string
  Required
  Nullable
  URL to the next page of items. ( null if none)
  Example value: "https://api.spotify.com/v1/me/shows?offset=1&limit=1"
- offset
  integer
  Required
  The offset of the items returned (as set in the query or by default)
  Example value: 0
- previous
  string
  Required
  Nullable
  URL to the previous page of items. ( null if none)
  Example value: "https://api.spotify.com/v1/me/shows?offset=1&limit=1"
- total
  integer
  Required
  The total number of items available to return.
  Example value: 4
- Required
- href
  string
  Required
  A link to the Web API endpoint returning the full result of the request
  Example value: "https://api.spotify.com/v1/me/shows?offset=0&limit=20"
- limit
  integer
  Required
  The maximum number of items in the response (as set in the query or by default).
  Example value: 20
- next
  string
  Required
  Nullable
  URL to the next page of items. ( null if none)
  Example value: "https://api.spotify.com/v1/me/shows?offset=1&limit=1"
- offset
  integer
  Required
  The offset of the items returned (as set in the query or by default)
  Example value: 0
- previous
  string
  Required
  Nullable
  URL to the previous page of items. ( null if none)
  Example value: "https://api.spotify.com/v1/me/shows?offset=1&limit=1"
- total
  integer
  Required
  The total number of items available to return.
  Example value: 4
- Required
- href
  string
  Required
  A link to the Web API endpoint returning the full result of the request
  Example value: "https://api.spotify.com/v1/me/shows?offset=0&limit=20"
- limit
  integer
  Required
  The maximum number of items in the response (as set in the query or by default).
  Example value: 20
- next
  string
  Required
  Nullable
  URL to the next page of items. ( null if none)
  Example value: "https://api.spotify.com/v1/me/shows?offset=1&limit=1"
- offset
  integer
  Required
  The offset of the items returned (as set in the query or by default)
  Example value: 0
- previous
  string
  Required
  Nullable
  URL to the previous page of items. ( null if none)
  Example value: "https://api.spotify.com/v1/me/shows?offset=1&limit=1"
- total
  integer
  Required
  The total number of items available to return.
  Example value: 4
- Required
- href
  string
  Required
  A link to the Web API endpoint returning the full result of the request
  Example value: "https://api.spotify.com/v1/me/shows?offset=0&limit=20"
- limit
  integer
  Required
  The maximum number of items in the response (as set in the query or by default).
  Example value: 20
- next
  string
  Required
  Nullable
  URL to the next page of items. ( null if none)
  Example value: "https://api.spotify.com/v1/me/shows?offset=1&limit=1"
- offset
  integer
  Required
  The offset of the items returned (as set in the query or by default)
  Example value: 0
- previous
  string
  Required
  Nullable
  URL to the previous page of items. ( null if none)
  Example value: "https://api.spotify.com/v1/me/shows?offset=1&limit=1"
- total
  integer
  Required
  The total number of items available to return.
  Example value: 4
- Required
- href
  string
  Required
  A link to the Web API endpoint returning the full result of the request
  Example value: "https://api.spotify.com/v1/me/shows?offset=0&limit=20"
- limit
  integer
  Required
  The maximum number of items in the response (as set in the query or by default).
  Example value: 20
- next
  string
  Required
  Nullable
  URL to the next page of items. ( null if none)
  Example value: "https://api.spotify.com/v1/me/shows?offset=1&limit=1"
- offset
  integer
  Required
  The offset of the items returned (as set in the query or by default)
  Example value: 0
- previous
  string
  Required
  Nullable
  URL to the previous page of items. ( null if none)
  Example value: "https://api.spotify.com/v1/me/shows?offset=1&limit=1"
- total
  integer
  Required
  The total number of items available to return.
  Example value: 4
- Required
- href
  string
  Required
  A link to the Web API endpoint returning the full result of the request
  Example value: "https://api.spotify.com/v1/me/shows?offset=0&limit=20"
- limit
  integer
  Required
  The maximum number of items in the response (as set in the query or by default).
  Example value: 20
- next
  string
  Required
  Nullable
  URL to the next page of items. ( null if none)
  Example value: "https://api.spotify.com/v1/me/shows?offset=1&limit=1"
- offset
  integer
  Required
  The offset of the items returned (as set in the query or by default)
  Example value: 0
- previous
  string
  Required
  Nullable
  URL to the previous page of items. ( null if none)
  Example value: "https://api.spotify.com/v1/me/shows?offset=1&limit=1"
- total
  integer
  Required
  The total number of items available to return.
  Example value: 4
- Required
- href
  string
  Required
  A link to the Web API endpoint returning the full result of the request
  Example value: "https://api.spotify.com/v1/me/shows?offset=0&limit=20"
- limit
  integer
  Required
  The maximum number of items in the response (as set in the query or by default).
  Example value: 20
- next
  string
  Required
  Nullable
  URL to the next page of items. ( null if none)
  Example value: "https://api.spotify.com/v1/me/shows?offset=1&limit=1"
- offset
  integer
  Required
  The offset of the items returned (as set in the query or by default)
  Example value: 0
- previous
  string
  Required
  Nullable
  URL to the previous page of items. ( null if none)
  Example value: "https://api.spotify.com/v1/me/shows?offset=1&limit=1"
- total
  integer
  Required
  The total number of items available to return.
  Example value: 4
- Required