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+blues.

Encoding spaces
Encode spaces with the hex code %20, %2B 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+NOT+blues 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+OR+blues 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, 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+artist: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+year:2014) or date range (for example, q=bob+year: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, upc, and isrc. For example, q=lil+genre:%22southern+hip+hop%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 objects to return. Default: 20. Minimum: 1. Maximum: 50.
offset
Optional. The index of the first object to return. Default: 0 (i.e., the first object). Use with limit to get the next set of objects.

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

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 is calculated from both total plays and most recent plays.
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.

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.

Example Request (artist)

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

Try it in our Web API Console

Example Request (artist with wildcard)

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

Try it in our Web API Console

Example Request (artist 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 Request (album 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 Request (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 Request (playlist with name/description)

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

Try it in our Web API Console