Search for an Item

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

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.

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.
type	Required. 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.
market	Optional. 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_markets	array of strings	The 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_urls	an external URL object	Known external URLs for this album.
href	string	A 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"
uri	string	The Spotify URI for the album.

artist object (full)

Key	Value Type	Value Description
external_urls	an external URL object	Known external URLs for this artist.
followers	A followers object	Information 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.)
href	string	A 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"`
uri	string	The 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 objects	The 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 object	Known external IDs for the track.
external_urls	an external URL object	Known external URLs for this track.
href	string	A link to the Web API endpoint providing full details of the track.
id	string	The Spotify ID for the track.
is_playable	boolean	Part of the response when Track Relinking is applied. If `true`, the track is playable in the given market. Otherwise `false`.
linked_from	a linked track object	Part 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	string	The object type: "track".
uri	string	The Spotify URI for the track.

paging object

Key	Value Type	Value Description
href	string	A link to the Web API endpoint returning the full result of the request.
items	an array of objects	The requested data.
limit	integer	The 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)
offset	integer	The 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

Newsletter

Endpoints

Request Parameters

Response Format

Example

album object (simplified)

artist object (full)

track object (full)

paging object

Example Request (artist)

Example Request (artist with wildcard)

Example Request (artist with name matching “Bob”, and offset and limit)

Example Request (album with name matching “Arrival” and artist matching “ABBA”)

Example Request (album with specific UPC code)

Example Request (playlist with name/description)