Get Spotify catalog information about artists, albums, tracks or playlists that match a keyword string.

Endpoints

GET https://api.spotify.com/v1/search

Request Parameters

Header field
Value
Authorization
Required if market=from_token is supplied in the query string, otherwise optional. A valid access token from the Spotify Accounts service: see the Web API Authorization Guide for details. Supplying this field/value in the request header guarantees improved rate limits for search queries.

If market=from_token is supplied in the query string, the current user must have authorized the user-read-private scope. See: Using Scopes.
Query parameter
Value
q
Required. The search query's keywords (and optional field filters and operators), for example q=roadhouse%20blues.

Encoding spaces
Encode spaces with the hex code %20 or +.

Keyword matching
Matching of search keywords is not case-sensitive. (Operators, however, should be specified in uppercase.)

Keywords will be matched in any order unless surrounded by double quotation marks: q=roadhouse&20blues will match both "Blues Roadhouse" and "Roadhouse of the Blues" while q="roadhouse&20blues" will match "My Roadhouse Blues" but not "Roadhouse of the Blues".

Searching for playlists will return results where the query keyword(s) match any part of the playlist's name or description. Only popular public playlists are returned.

Operators
The operator NOT can be used to exclude results. For example q=roadhouse%20NOT%20blues returns items that match "roadhouse" but excludes those that also contain the keyword "blues".

Similarly, the OR operator can be used to broaden the search: q=roadhouse%20OR%20blues returns all results that include either of the terms. Only one OR operator can be used in a query.

Note that operators must be specified in uppercase otherwise they will be treated as normal keywords to be matched.

Wildcards
The asterisk (*) character can, with some limitations, be used as a wildcard (maximum: 2 per query). It will match a variable number of non-white-space characters. It cannot be used in a quoted phrase, in a field filter, when there is a dash ("-") in the query, or as the first character of the keyword string.

Field filters
By default, results are returned when a match is found in any field of the target object type. Searches can be made more specific by specifying an album, artist or track field filter. For example, the query q=album:gold%20artist:abba&type=album will only return albums with the text "gold" in the album name and the text "abba" in the artist's name.

The field filter year can be used with album, artist and track searches to limit the results to a particular year (for example, q=bob%20year:2014) or date range (for example, q=bob%20year:1980-2020).

The field filter tag:new can be used in album searches to retrieve only albums released in the last two weeks. The field filter tag:hipster can be used in album searches to retrieve only albums with the lowest 10% popularity.

Other possible field filters, depending on object types being searched, include genre (applicable to tracks and artists), upc, and isrc. For example, q=lil%20genre:%22southern%20hip%20hop%22&type=artist. Use double quotation marks around the genre keyword string if it contains spaces.

typeRequired. A comma-separated list of item types to search across. Valid types are: album, artist, playlist, and track.

Search results will include hits from all the specified item types; for example q=name:abacab&type=album,track will return both albums and tracks with "abacab" in their name.
marketOptional. An ISO 3166-1 alpha-2 country code or the string from_token.

If a country code is given, only artists, albums, and tracks with content playable in that market will be returned. (Playlist results are not affected by the market parameter.)

If from_token is given and a valid access token is supplied in the request header, only items with content playable in the country associated with the user's account will be returned. (The country associated with the user's account can be viewed by the user in their account settings at https://www.spotify.com/se/account/overview/). Note that the user must have granted access to the user-read-private scope when the access token was issued.
limit
Optional. The maximum number of results to return. Default: 20. Minimum: 1. Maximum: 50.
offset
Optional. The index of the first result to return. Default: 0 (i.e., the first result). Maximum offset: 100.000. Use with limit to get the next page of search results.

Response Format

On success, the HTTP status code in the response header is 200 OK and the response body contains an array of artist objects, simplified album objects and/or track objects (wrapped in a paging object) in JSON format. On error, the header status code is an error code and the response body contains an error object.

Example

curl -X GET "https://api.spotify.com/v1/search?q=tania%20bowra&type=artist"
{
  "artists": {
    "href": "https://api.spotify.com/v1/search?query=tania+bowra&offset=0&limit=20&type=artist",
    "items": [ {
      "external_urls": {
        "spotify": "https://open.spotify.com/artist/08td7MxkoHQkXnWAYD8d6Q"
      },
      "genres": [ ],
      "href": "https://api.spotify.com/v1/artists/08td7MxkoHQkXnWAYD8d6Q",
      "id": "08td7MxkoHQkXnWAYD8d6Q",
      "images": [ {
        "height": 640,
        "url": "https://d3rt1990lpmkn.cloudfront.net/original/f2798ddab0c7b76dc2d270b65c4f67ddef7f6718",
        "width": 640
      }, {
        "height": 300,
        "url": "https://d3rt1990lpmkn.cloudfront.net/original/b414091165ea0f4172089c2fc67bb35aa37cfc55",
        "width": 300
      }, {
        "height": 64,
        "url": "https://d3rt1990lpmkn.cloudfront.net/original/8522fc78be4bf4e83fea8e67bb742e7d3dfe21b4",
        "width": 64
      } ],
      "name": "Tania Bowra",
      "popularity": 0,
      "type": "artist",
      "uri": "spotify:artist:08td7MxkoHQkXnWAYD8d6Q"
    } ],
    "limit": 20,
    "next": null,
    "offset": 0,
    "previous": null,
    "total": 1
  }
}

Try it in our Web API Console

More examples

Example: Searching for artists

curl -X GET "https://api.spotify.com/v1/search?q=tania%20bowra&type=artist"

Try it in our Web API Console

Example: Searching for artists, using a wildcard

curl -X GET "https://api.spotify.com/v1/search?q=tania*&type=artist"

Try it in our Web API Console

Example: Searching for artists with name matching “Bob”, and offset and limit

curl -X GET "https://api.spotify.com/v1/search?q=bob&type=artist&offset=20&limit=2"

Try it in our Web API Console

Example: Searching for albums with name matching “Arrival” and artist matching “ABBA”

curl -X GET "https://api.spotify.com/v1/search?q=album:arrival%20artist:abba&type=album"

Try it in our Web API Console

Example: Searching for album with specific UPC code

curl -X GET "https://api.spotify.com/v1/search?q=upc:5099908217059&type=album"

Try it in our Web API Console

Example: Searching for playlists with name or description matching a string

curl -X GET "https://api.spotify.com/v1/search?q="doom metal"&type=playlist"

Try it in our Web API Console

Example: Searching only for tracks available in a specific market

curl -X GET "https://api.spotify.com/v1/search?q=abba&type=track&market=US"

Try it in our Web API Console

Fields Reference

album object (simplified)

Key
Value Type
Value Description
album_type
string
The type of the album: one of "album", "single", or "compilation".
available_marketsarray of stringsThe markets in which the album is available: ISO 3166-1 alpha-2 country codes. Note that an album is considered available in a market when at least 1 of its tracks is available in that market.
external_urlsan external URL objectKnown external URLs for this album.
hrefstringA link to the Web API endpoint providing full details of the album.
id
string
The Spotify ID for the album.
images
array of image objects
The cover art for the album in various sizes, widest first.
name
string
The name of the album.
type
string
The object type: "album"
uristringThe Spotify URI for the album.

artist object (full)

Key
Value Type
Value Description
external_urlsan external URL objectKnown external URLs for this artist.
followersA followers objectInformation about the followers of the artist.
genres
array of strings
A list of the genres the artist is associated with. For example: "Prog Rock", "Post-Grunge". (If not yet classified, the array is empty.)
hrefstringA link to the Web API endpoint providing full details of the artist.
id
string
The Spotify ID for the artist.
images
array of image objects
Images of the artist in various sizes, widest first.
name
string
The name of the artist
popularity
int
The popularity of the artist. The value will be between 0 and 100, with 100 being the most popular. The artist's popularity is calculated from the popularity of all the artist's tracks.
type
string
The object type: "artist"
uristringThe Spotify URI for the artist.

track object (full)

Key
Value Type
Value Description
album
a simplified album object
The album on which the track appears. The album object includes a link in href to full information about the album.
artists
an array of simplified artist objectsThe artists who performed the track. Each artist object includes a link in href to more detailed information about the artist.
available_markets
array of strings
A list of the countries in which the track can be played, identified by their ISO 3166-1 alpha-2 code.
disc_number
integer
The disc number (usually 1 unless the album consists of more than one disc).
duration_ms
integer
The track length in milliseconds.
explicit
Boolean
Whether or not the track has explicit lyrics (true = yes it does; false = no it does not OR unknown).
external_ids
an external ID objectKnown external IDs for the track.
external_urlsan external URL objectKnown external URLs for this track.
hrefstringA link to the Web API endpoint providing full details of the track.
id
stringThe Spotify ID for the track.
is_playablebooleanPart of the response when Track Relinking is applied. If true, the track is playable in the given market. Otherwise false.
linked_froma linked track objectPart of the response when Track Relinking is applied, and the requested track has been replaced with different track. The track in the linked_from object contains information about the originally requested track.
name
string
The name of the track.
popularity
integer
The popularity of the track. The value will be between 0 and 100, with 100 being the most popular.

The popularity of a track is a value between 0 and 100, with 100 being the most popular. The popularity is calculated by algorithm and is based, in the most part, on the total number of plays the track has had and how recent those plays are.

Generally speaking, songs that are being played a lot now will have a higher popularity than songs that were played a lot in the past. Duplicate tracks (e.g. the same track from a single and an album) are rated independently. Artist and album popularity is derived mathematically from track popularity. Note that the popularity value may lag actual popularity by a few days: the value is not updated in real time.
preview_url
string
A link to a 30 second preview (MP3 format) of the track.
track_number
integer
The number of the track. If an album has several discs, the track number is the number on the specified disc.
type
stringThe object type: "track".
uristringThe Spotify URI for the track.

playlist object (simplified)

Key
Value Type
Value Description
collaborative
Booleantrue if the owner allows other users to modify the playlist.
external_urlsan external URL object Known external URLs for this playlist.
hrefstringA link to the Web API endpoint providing full details of the playlist.
id
string
The Spotify ID for the playlist.
imagesan array of image objectsImages for the playlist. The array may be empty or contain up to three images. The images are returned by size in descending order. See Working with Playlists.

Note: If returned, the source URL for the image (url) is temporary and will expire in less than a day.
name
string
The name of the playlist.
owner
a user objectThe user who owns the playlist
public
Boolean or nullThe playlist's public/private status: true the playlist is public, false the playlist is private, null the playlist status is not relevant. For more about public/private status, see Working with Playlists.
snapshot_idstringThe version identifier for the current playlist. Can be supplied in other requests to target a specific playlist version
tracksa tracks objectA collection containing a link (href) to the Web API endpoint where full details of the playlist's tracks can be retrieved, along with the total number of tracks in the playlist.
type
string
The object type: "playlist"
uristringThe Spotify URI for the playlist.

paging object

Key
Value Type
Value Description
hrefstringA link to the Web API endpoint returning the full result of the request.
itemsan array of objectsThe requested data.
limitintegerThe maximum number of items in the response (as set in the query or by default).
next
string
URL to the next page of items. (null if none)
offsetintegerThe offset of the items returned (as set in the query or by default).
previous
string
URL to the previous page of items. (null if none)
total
integer
The total number of items available to return.

Frequently Asked Questions about Search

Can I sort the results? For instance, alphabetically or by release date

Unfortunately at the moment there is no way to fetch sorted results from the Web API.

Why does Search return full objects for tracks, but only partial albums?

It’s a fine balance between keeping the response small but at the same time include as much information as possible. We’ve expanded response objects previously, and we’ll definitely keep this in mind as we tweak the Search endpoint.

Is it possible to filter the search for more than one genre?

No, you can only search one genre at a time.

Is it possible to query based on release date?

You can query at a year level using the year:. For instance https://api.spotify.com/v1/search?q=bob%20year:2014&type=album will return albums released in 2014 with their name or artists containing “bob”. You can also use the “tag:new” field filter to get just those albums (and compilations and singles) released in the last 2 weeks.

What about searching for playlists that contain a certain track?

Unfortunately, this is not supported yet.

And searching for playlists within a user’s library?

No, it’s not possible. You would need to fetch the user’s playlists and go through them.