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.

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.

searchPlaylists()

Searches playlists according to filters on BeatSaver.

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	error	boolean	Returns when there are playlists found with the filters/on the current page/with the query.