Categories Endpoint Reference

Functions

async get_several_browse_categories(client: SpotanticClient, *, limit: int = 20, offset: int = 0, locale: SpotifyLocaleID | None = None) → APICallModel[GetSeveralBrowseCategoriesRequest, JsonAPIResponse, PagedResultModel[CategoryModel]]

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

Deprecated since version 0.1.0: This endpoint is deprecated since 11 February 2026 for new users. Existing users may be able to continue using it. More information on the deprecation can be found in the Spotify API documentation: Update on Developer Access and Platform Security.

Parameters:

  • client – SpotanticClient instance.

  • limit – The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50.

  • offset – The index of the first item to return. Default: 0 (the first item). Use with limit to get the next set of items.

  • locale – The desired language, consisting of an ISO 639-1 language code and an ISO 3166-1 alpha-2 country code, joined by an underscore.

Returns:

An object containing the request used to obtain the response, the retrieved data and parsed data as model.

async get_single_browse_category(client: SpotanticClient, *, category_id: str, locale: SpotifyLocaleID | None = None) → APICallModel[GetSingleBrowseCategoryRequest, JsonAPIResponse, CategoryModel]

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

Deprecated since version 0.1.0: This endpoint is deprecated since 11 February 2026 for new users. Existing users may be able to continue using it. More information on the deprecation can be found in the Spotify API documentation: Update on Developer Access and Platform Security.

Parameters:

  • client – SpotanticClient instance.

  • category_id – The Spotify ID for the browse category.

  • locale – The desired language, consisting of an ISO 639-1 language code and an ISO 3166-1 alpha-2 country code, joined by an underscore.

Returns:

An object containing the request used to obtain the response, the retrieved data and parsed data as model.

Request models

class GetSeveralBrowseCategoriesRequest(*, required_scopes: set[AuthScope] = <factory>, url: HttpUrl | None = None, endpoint: str | None = 'browse/categories', method_type: HTTPMethod = <HTTPMethod.GET>, headers: RequestHeadersModel = <factory>, params: GetSeveralBrowseCategoriesRequestParams | None = None, body: None = None)

Bases: RequestModel[GetSeveralBrowseCategoriesRequestParams, NoneType]

Request model for Get Several Browse Categories endpoint.

classmethod build(*, limit: int = 20, offset: int = 0, locale: SpotifyLocaleID | None = None) → GetSeveralBrowseCategoriesRequest

Builds a request model based on given parameters.

The function automatically determines the endpoint if it is not static. Also, it automatically assigns parameters to request query or body.

Parameters:

  • limit – The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50.

  • offset – The index of the first item to return. Default: 0 (the first item). Use with limit to get the next set of items.

  • locale – The desired language, consisting of an ISO 639-1 language code and an ISO 3166-1 alpha-2 country code, joined by an underscore.

Returns:

Validated Request object.

endpoint: str | None

Endpoint associated with the request.

method_type: HTTPMethod

HTTP method for the request.

class GetSeveralBrowseCategoriesRequestParams(*, locale: SpotifyLocaleID | None = None, limit: Annotated[int, Ge(ge=1), Le(le=50)], offset: int)

Bases: BaseModel

Params model for Get Several Browse Categories request.

limit: Annotated[int, Field(ge=1, le=50)]

The maximum number of items to return.

locale: SpotifyLocaleID | None

The desired language, consisting of an ISO 639-1 language code and an ISO 3166-1 alpha-2 country code, joined by an underscore.

offset: int

The index of the first item to return.

class GetSingleBrowseCategoryRequest(*, required_scopes: set[AuthScope] = <factory>, url: HttpUrl | None = None, endpoint: str | None = None, method_type: HTTPMethod = <HTTPMethod.GET>, headers: RequestHeadersModel = <factory>, params: GetSingleBrowseCategoryRequestParams | None = None, body: None = None)

Bases: RequestModel[GetSingleBrowseCategoryRequestParams, NoneType]

Request model for Get Single Browse Category endpoint.

classmethod build(*, category_id: str, locale: SpotifyLocaleID | None = None) → GetSingleBrowseCategoryRequest

Builds a request model based on given parameters.

The function automatically determines the endpoint if it is not static. Also, it automatically assigns parameters to request query or body.

Parameters:

  • category_id – The Spotify ID for the browse category.

  • locale – The desired language, consisting of an ISO 639-1 language code and an ISO 3166-1 alpha-2 country code, joined by an underscore.

Returns:

Validated Request object.

method_type: HTTPMethod

HTTP method for the request.

class GetSingleBrowseCategoryRequestParams(*, locale: SpotifyLocaleID | None = None, category_id: str)

Bases: BaseModel

Params model for Get Single Browse Category request.

category_id: str

The Spotify ID for the browse category.

locale: SpotifyLocaleID | None

The desired language, consisting of an ISO 639-1 language code and an ISO 3166-1 alpha-2 country code, joined by an underscore.

Response models

class GetSeveralBrowseCategoriesResponse(*, categories: PagedResultModel[CategoryModel])

Bases: BaseModel

Response model for Get Several Browse Categories endpoint.

categories: PagedResultModel[CategoryModel]

List of categories.