Search

Search

This page is documentation for the Search 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

searchMaps()

Searches maps 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 levels.		no	null
filters	object	Filters for search results.	Can only be as the provided format.	no	null

Filters usage

Parameters	Type	Explanation	Limitations	Required	Default value
automapper	boolean	Whether the map uses an automapper.	Can only be these options: true = both, false = only ai, null = no ai	no
chroma	boolean	Whether the map uses chroma.		no
cinema	boolean	Whether the map uses cinema.		no
curated	boolean	Whether the map is curated.		no
fullSpread	boolean	Whether the map is full spread.		no
me	boolean	Whether the map is/uses me. I don't know what that is.		no
noodle	boolean	Whether the map uses noodle.		no
ranked	boolean	Whether the map is ranked.		no
verified	boolean	Whether the map is verified.		no
from	string	Return maps created after this date. Format: YYYY-MM-DDTHH:MM:SS+00:00	Minimum year is 1970 and maximum is 9999.	no
to	string	Return maps created before this date. Format: YYYY-MM-DDTHH:MM:SS+00:00	Minimum year is 1970 and maximum is 9999.	no
maxBpm	number	Maximum bpm of a map.		no
minBpm	number	Minimum bpm of a map.		no
maxDuration	number	Maximum duration of a map.	Cannot be more than 9 characters.	no
minDuration	number	Minimum duration of a map.	Cannot be more than 9 characters.	no
maxNps	number	Maximum nps of a map.		no
minNps	number	Minimum nps of a map.		no
maxRating	number	Maximum rating of a map.		no
minRating	number	Minimum rating of a map.		no
sortOrder	string	Order levels by sort option.	Can only be these options: Latest, Relevance, Rating, Curated	no
tags	object	Whether the map has/doesn't have these tags.	Can only be as the provided format.	no

Tags usage

Parameters	Type	Explanation	Limitations	Required	Default value
excluded	array	Tags that are excluded from the search results. Doesn't need "!".		no
tags	array	Tags to search for.		no
or	array	Search for maps that have either the first or the second tag. Also can use exclude using "!" at the start of one of the tags.	Tags need to be in an array and most have two items in it. Example: ["tag1", "tag2"]	no

Returns

Status	Status type	Type	Explanation	Related parameter
invalidautomapper	error	string	Returns when automapper is not a boolean or null.	automapper
invalidchroma	error	string	Returns when chroma is not a boolean.	chroma
invalidcinema	error	string	Returns when cinema is not a boolean.	cinema
invalidcurated	error	string	Returns when curated is not a boolean.	curated
invalidfullspread	error	string	Returns when fullSpread is not a boolean.	fullSpread
invalidme	error	string	Returns when me is not a boolean.	me
invalidnoodle	error	string	Returns when noodle is not a boolean.	noodle
invalidranked	error	string	Returns when ranked is not a boolean.	ranked
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
invalidmaxbpm	error	string	Returns when maxBpm is not a number.	maxBpm
invalidminbpm	error	string	Returns when minBpm is not a number.	minBpm
invalidmaxnps	error	string	Returns when maxNps is not a number.	maxNps
invalidminnps	error	string	Returns when minNps is not a number.	minNps
invalidmaxrating	error	string	Returns when maxRating is not a number.	maxRating
invalidminrating	error	string	Returns when minRating is not a number.	minRating
invalidmaxduration	error	string	Returns when maxDuration is not a number.	maxDuration
invalidminduration	error	string	Returns when minDuration is not a number.	minDuration
invalidpage	error	string	Returns when page is not a number.	page
toolongpage	error	string	Returns when page is longer than 18 characters.	page
toolongmaxduration	error	string	Returns when maxDuration is longer than 9 characters.	maxDuration
toolongminduration	error	string	Returns when minDuration is longer than 9 characters.	minDuration
invalidquery	error	string	Returns when query is not a string or empty.	query
invalidtags	error	string	Refer to the tag returns section with the error data provided in the data property.	tags
invalidsortorder	error	string	Returns when sortOrder is not one of the specified 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 maps are found with the filters/on the current page/with the query.
true	success	boolean	Returns when there are maps found with the filters/on the current page/with the query.

Tag returns

Tag type	Error type	Type	Explanation	Related parameter
tag	string	string	One of the elements in tags is not a string.	tags
tag	emptystring	string	One of the elements in tags is an empty string.	tags
excludedTag	string	string	One of the elements in excluded is not a string.	excluded
excludedTag	emptystring	string	One of the elements in excluded is an empty string.	excluded
orTag	insufficientdata	string	One of the arrays in the or array doesn't have two elements.	or
orTag	string	string	One of the arrays in the or array has an element that is not a string.	or
orTag	emptystring	string	One of the arrays in the or array has an element that is an empty string.	or

Example

Usage

var response = await bsAPI.searchMaps(0, "test", {
    automapper: null,
    chroma: false,
    cinema: false,
    curated: false,
    fullSpread: false,
    me: false,
    noodle: false,
    ranked: false,
    verified: false,
    from: "2021-10-20T15:30:00+00:00",
    to: "2023-10-20T15:30:00+00:00",
    maxBpm: 250,
    minBpm: 90,
    maxDuration: 300,
    minDuration: 120,
    maxNps: 2,
    minNps: 1,
    maxRating: 10,
    minRating: 0,
    sortOrder: "Latest",
    tags: {
        excluded: ["anime"],
        tags: ["rock"],
        or: [["accuracy", "pop"]],
    },
});

Response

Refer to responses page. Response data type: SearchResponse