Playlists

Playlists

This page is documentation for the Playlists API for BeatSaver. All methods return an object with a status and data property. The data property always returns the raw api data when the call is successful. This might change in later versions. Wrapper is imported as bsAPI in all examples. For more information refer to responses.

Common return values

unhandledError

Returns when the library runs into an unhandled error. This only raises an error when debug is enabled/in the beta branch. This behaviour is disabled in the release/main branch. When debug is disabled it returns an unhandlederror status and the error data in the data property. Please report these unhandled errors into the issue tracker in the project repository.

fetchError

Returns when the library runs into some kind of network error. Also returns error data in the data property.

Currently catched network errors

• ERR_BAD_REQUEST (not always)
• ENOTFOUND
• ECONNREFUSED
• ETIMEDOUT
• ECONNRESET
• ENETUNREACH

Methods

getLatestPlaylists()

Gets latest uploaded playlists. You can also specify before and after dates and sort options.

Usage

Parameters	Type	Explanation	Limitations	Required	Default value
before	string	Return maps created before this date.	Minimum year is 1970 and maximum is 9999.	no	null
after	string	Return maps created after this date.	Minimum year is 1970 and maximum is 9999.	no	null
sort	string	Sort maps by sort option. (UPDATED, SONGS_UPDATED, CREATED)	Must be one of the provided sort options.	no	null

Returns

Status	Status type	Type	Explanation	Related parameter
invalidbeforedate	error	string	Returns when before date is not in the correct format.	before
invalidafterdate	error	string	Returns when after date is not in the correct format.	after
invalidsort	error	string	Returns when sort is not one of the provided sort options.	sort
fetcherror	error	string	Refer to fetcherror in common return values.
unhandlederror	error	string	Refer to unhandederror in common return values.
false	error	string	Returns if no playlists are found.
true	success	string	Returns if playlists are found.

Example

Usage

var response = await bsAPI.getLatestPlaylists("2022-10-20T15:30:00+00:00", "2020-10-20T15:30:00+00:00", "UPDATED");

Response

Refer to responses page. Response data type: PlaylistSearchResponse

searchPlaylists()

Searches playlists according to filters on BeatSaver. For some reason the API doesn't care about the dates and the max and minNps. This is a problem with the API not the wrapper because I tried it in the Swagger UI and it also didn't work. If you know the problem or the problem is fixed please open an issue or contact me.

Usage

Parameters	Type	Explanation	Limitations	Required	Default value
page	number	Page of the search results.	Cannot be more than 18 characters.	no	0
query	string	Search query for playlists.		no	null
filters	object	Filters for playlist searches.	Can only be as the provided format.	no	null

Filters usage

Parameters	Type	Explanation	Limitations	Required	Default value
curated	boolean	Whether the playlist is curated.		no
includeEmpty	boolean	Whether it should return empty playlists.		no
verified	boolean	Whether the playlist is verified.		no
from	string	Return playlists created after this date. Format: YYYY-MM-DDTHH:MM:SS+00:00	Minimum year is 1970 and maximum is 9999.	no
to	string	Return playlists created before this date. Format: YYYY-MM-DDTHH:MM:SS+00:00	Minimum year is 1970 and maximum is 9999.	no
maxNps	number	Maximum nps of a playlist.		no
minNps	number	Minimum nps of a playlist.		no
sortOrder	string	Order playlists by sort option.	Can only be these options: Latest, Relevance, Rating, Curated	no

Returns

Status	Status type	Type	Explanation	Related parameter
invalidcurated	error	string	Returns when curated is not a boolean.	curated
invalidincludeempty	error	string	Returns when includeEmpty is not a boolean.	includeEmpty
invalidverified	error	string	Returns when verified is not a boolean.	verified
invalidfromdate	error	string	Returns when from date is not in the correct format.	from
invalidtodate	error	string	Returns when to date is not in the correct format.	to
invalidmaxnps	error	string	Returns when maxNps is not a number.	maxNps
invalidminnps	error	string	Returns when minNps is not a number.	minNps
invalidpage	error	string	Returns when page is not a number.	page
toolongpage	error	string	Returns when page is longer than 18 characters.	page
invalidquery	error	string	Returns when query is not a string or empty.	query
invalidsortorder	error	string	Returns when sortOrder is not one of the provided sort options. (Latest, Relevance, Rating, Curated)	sortOrder
fetcherror	error	string	Refer to fetcherror in common return values.
unhandlederror	error	string	Refer to unhandederror in common return values.
false	error	boolean	Returns when no playlists are found with the filters/on the current page/with the query.
true	success	boolean	Returns when there are playlists found with the filters/on the current page/with the query.

Example

Usage

var response = await bsAPI.searchPlaylists(0, "test", {
    curated: false,
    includeEmpty: false,
    verified: false,
    from: "2020-10-20T15:30:00+00:00",
    to: "2022-10-20T15:30:00+00:00",
    maxNps: 2,
    minNps: 1,
    sortOrder: "Latest",
});

Response

Refer to responses page. Response data type: PlaylistSearchResponse

getPlaylistByID()

Gets playlist by playlist ID.

Usage

Parameters	Type	Explanation	Limitations	Required	Default value
playlistID	number	ID for playlist on BeatSaver.	Cannot be more than 9 characters.	yes
page	number	Page of the results.	Cannot be more than 18 characters.	no	0

Returns

Status	Status type	Type	Explanation	Related parameter
invalidid	error	string	Returns when playlistID is not a number.	playlistID
invalidpage	error	string	Returns when page is not a number.	page
toolongid	error	string	Returns when playlistID is longer than 9 characters.	playlistID
toolongpage	error	string	Returns when page is longer than 18 characters.	page
fetcherror	error	string	Refer to fetcherror in common return values.
unhandlederror	error	string	Refer to unhandederror in common return values.
false	error	boolean	Returns when no playlist has been found with the ID.
true	success	boolean	Returns when playlist has been found with the ID.

Example

Usage

Example playlistID:

• playlistID 82685: Teminite Pack by Alphabeat (https://beatsaver.com/playlists/82685)

var response = await bsAPI.getPlaylistByID(82685, 0);

Response

Refer to responses page. Response data type: PlaylistPage

getPlaylistsByUserID()

Gets all playlists created by the user linked to the userID.

Usage

Parameters	Type	Explanation	Limitations	Required	Default value
userID	number	ID for user on BeatSaver.	Cannot be more than 9 characters.	yes
page	number	Page of the results.	Cannot be more than 18 characters.	no	0

Returns

Status	Status type	Type	Explanation	Related parameter
invalidid	error	string	Returns when userID is not a number.	userID
invalidpage	error	string	Returns when page is not a number.	page
toolongid	error	string	Returns when userID is longer than 9 characters.	userID
toolongpage	error	string	Returns when page is longer than 18 characters.	page
fetcherror	error	string	Refer to fetcherror in common return values.
unhandlederror	error	string	Refer to unhandederror in common return values.
false	error	string	Returns when no playlists have been found or the user doesn't exist.
true	success	string	Returns when playlists have been found.

Example

Usage

Example userID:

• userID 5122: Alphabeat (https://beatsaver.com/profile/5122)

var response = await bsAPI.getPlaylistsByUserID(5122, 0);

Response

Refer to responses page. Response data type: PlaylistSearchResponse