Get a List of Categories

Get a list of categories used to tag items in Spotify (on, for example, the Spotify player’s “Browse” tab).

Endpoint

GET https://api.spotify.com/v1/browse/categories

Request Parameters

Header field	Value
Authorization	Required. A valid access token from the Spotify Accounts service: see the Web API Authorization Guide for details.

Query parameter	Value
country	Optional. A country: an ISO 3166-1 alpha-2 country code. Provide this parameter if you want to narrow the list of returned categories to those relevant to a particular country. If omitted, the returned items will be globally relevant.
locale	Optional. The desired language, consisting of an ISO 639 language code and an ISO 3166-1 alpha-2 country code, joined by an underscore. For example: `es_MX`, meaning "Spanish (Mexico)". Provide this parameter if you want the category metadata returned in a particular language. Note that, if `locale` is not supplied, or if the specified language is not available, the category strings returned will be in the Spotify default language (American English). The `locale` parameter, combined with the `country` parameter, may give odd results if not carefully matched. For example `country=SE&locale=de_DE` will return a list of categories relevant to Sweden but as German language strings.
limit	Optional. The maximum number of categories to return. Default: 20. Minimum: 1. Maximum: 50.
offset	Optional. The index of the first item to return. Default: 0 (the first object). Use with `limit` to get the next set of categories.

Response Format

On success, the HTTP status code in the response header is 200 OK and the response body contains an object with a categories field, with an array of category 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.

Once you have retrieved the list, you can use Get a Category to drill down further.

Example

curl -i -X GET "https://api.spotify.com/v1/browse/categories" -H "Authorization: Bearer {your access token}"

{
  "categories" : {
    "href" : "https://api.spotify.com/v1/browse/categories?offset=0&limit=20",
    "items" : [ {
      "href" : "https://api.spotify.com/v1/browse/categories/toplists",
      "icons" : [ {
        "height" : 275,
        "url" : "https://datsnxq1rwndn.cloudfront.net/media/derived/toplists_11160599e6a04ac5d6f2757f5511778f_0_0_275_275.jpg",
        "width" : 275
      } ],
      "id" : "toplists",
      "name" : "Top Lists"
    }, {
      "href" : "https://api.spotify.com/v1/browse/categories/mood",
      "icons" : [ {
        "height" : 274,
        "url" : "https://datsnxq1rwndn.cloudfront.net/media/original/mood-274x274_976986a31ac8c49794cbdc7246fd5ad7_274x274.jpg",
        "width" : 274
      } ],
      "id" : "mood",
      "name" : "Mood"
    }, {
      "href" : "https://api.spotify.com/v1/browse/categories/party",
      "icons" : [ {
        "height" : 274,
        "url" : "https://datsnxq1rwndn.cloudfront.net/media/derived/party-274x274_73d1907a7371c3bb96a288390a96ee27_0_0_274_274.jpg",
        "width" : 274
      } ],
      "id" : "party",
      "name" : "Party"
    }, {
      "href" : "https://api.spotify.com/v1/browse/categories/pop",
      "icons" : [ {
        "height" : 274,
        "url" : "https://datsnxq1rwndn.cloudfront.net/media/derived/pop-274x274_447148649685019f5e2a03a39e78ba52_0_0_274_274.jpg",
        "width" : 274
      } ],
      "id" : "pop",
      "name" : "Pop"
    }, {
      "href" : "https://api.spotify.com/v1/browse/categories/workout",
      "icons" : [ {
        "height" : 275,
        "url" : "https://datsnxq1rwndn.cloudfront.net/media/derived/workout_856581c1c545a5305e49a3cd8be804a0_0_0_275_275.jpg",
        "width" : 275
      } ],
      "id" : "workout",
      "name" : "Workout"
    }, ... ],
    "limit" : 20,
    "next" : "https://api.spotify.com/v1/browse/categories?offset=20&limit=20",
    "offset" : 0,
    "previous" : null,
    "total" : 31
  }
}

Try it in our Web API Console

category object

Key	Value Type	Value Description
href	string	A link to the Web API endpoint returning full details of the category.
icons	an array of image objects	The category icon, in various sizes.
id	string	The Spotify category ID of the category.
name	string	The name of the category.

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.

Newsletter