Maps

Maps

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

getMapInfo()

Returns information about the map with the ID that is provided.

Usage

Parameters	Type	Explanation	Limitations	Required	Default value
id	string	ID for map.		yes

Returns

Status	Status type	Type	Explanation	Related parameter
invalidid	error	string	Returns when ID is empty or null.	id
false	error	boolean	Returns when map with provided ID is not found.
fetcherror	error	string	Refer to fetcherror in common return values.
unhandlederror	error	string	Refer to unhandederror in common return values.
true	success	boolean	Returns when map has been found.

Example

Usage

Example ID:

• ID 9e11: PhaseOne - Digital (ft. Periphery) mapped by nitronik.exe (https://beatsaver.com/maps/9e11)

var response = await bsAPI.getMapInfo("9e11");

Response

Refer to responses page. Response data type: MapDetail

getMapInfoFromList()

Returns all maps that are in the provided array. Doesn't fail when some IDs are invalid.

Usage

Parameters	Type	Explanation	Limitations	Required	Default value
idList	array	Array of map IDs.	Array can't have more than 50 IDs.	yes

Returns

Status	Status type	Type	Explanation	Related parameter
notanarray	error	string	Returns when the provided parameter is not an array.	idList
emptyarray	error	string	Returns when the provided array is empty.	idList
toolargearray	error	string	Returns when the provided array has more than 50 IDs.	idList
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 the provided array has no valid map IDs.
true	success	boolean	Returns when the provided array has valid map IDs.

Example

Usage

Example IDs:

• ID 9e11: PhaseOne - Digital (ft. Periphery) mapped by nitronik.exe (https://beatsaver.com/maps/9e11)
• ID 36693: Aweminus - ClublandLV mapped by spinposts (https://beatsaver.com/maps/36693)

var response = await bsAPI.getMapInfoFromList(["9e11", "36693"]);

Response

Refer to responses page. Response data type: MapDetail

getMapInfoFromHashList()

Returns all maps that are in the provided array. Similar to getMapInfoFromList() but uses map hashes instead of map IDs. Also doesn't fail when there are some invalid hashes.

Usage

Parameters	Type	Explanation	Limitations	Required	Default value
hashList	array	Array of map hashes.	Array can't have more than 50 hashes.	yes

Returns

Status	Status type	Type	Explanation	Related parameter
notanarray	error	string	Returns when the provided parameter is not an array.	hashList
emptyarray	error	string	Returns when the provided array is empty.	hashList
toolargearray	error	string	Returns when the provided array has more than 50 hashes.	hashList
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 the provided array has no valid map hashes.
true	success	boolean	Returns when the provided array has valid map hashes.

Example

Usage

Example hashes:

• Hash 60BD62BD5F0D2555BB001D5EA3D8E28FEC6F07CE: PhaseOne - Digital (ft. Periphery) mapped by nitronik.exe (https://beatsaver.com/maps/9e11)
• Hash 585302A75BA65628296B3029705A76DEC4D5A02B: Venjent - Create Machines mapped by Tsunami_Pro (https://beatsaver.com/maps/311cf)

var response = await bsAPI.getMapInfoFromHashList(["60BD62BD5F0D2555BB001D5EA3D8E28FEC6F07CE", "585302A75BA65628296B3029705A76DEC4D5A02B"]);

Response

Refer to responses page. Response data type: MapDetail

getMapsFromUserID()

Returns maps created by user linked to the userID.

Usage

Parameters	Type	Explanation	Limitations	Required	Default value
userID	number	Registered user's userID on BeatSaver.	Cannot be more than 9 characters.	yes
page	number	Page of the user's created maps.	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
toolongid	error	string	Returns when userID is longer than 9 characters.	userID
toolongpage	error	string	Returns when page is longer than 18 characters.	page
invalidpage	error	string	Returns when page is not a number.	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 user's maps couldn't be found.
true	success	boolean	Returns when user's maps had been found.

Example

Usage

Example userID:

• userID 58338: Joetastic (https://beatsaver.com/profile/58338)

var response = await bsAPI.getMapsFromUserID(58338, 0);

Response

Refer to responses page. Response data type: SearchResponse

getCollaborationMapsFromUserID()

Returns maps that the user linked to the userID contributed to.

Usage

Parameters	Type	Explanation	Limitations	Required	Default value
userID	number	Registered user's userID on Beatsaver.	Cannot be more than 9 characters.	yes
pageSize	number	Number of maps to return.	Cannot be more than 9 characters.	no	20
before	string	Return maps before this date. Format: YYYY-MM-DDTHH:MM:SS+00:00	Minimum year is 1970 and maximum is 9999.	no	null

Returns

Status	Status type	Type	Explanation	Related parameter
invalidid	error	string	Returns when userID is not a number.	userID
toolongid	error	string	Returns when userID is longer than 9 characters.	userID
toolongpagesize	error	string	Returns when pageSize is longer than 9 characters.	pageSize
invalidpagesize	error	string	Returns when pageSize is not a number.	pageSize
invaliddate	error	string	Returns when before date isn't in the correct format.	before
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.
true	success	boolean	Returns when maps had been found.

Example

Usage

Example userID:

• userID 58338: Joetastic (https://beatsaver.com/profile/58338)

var response = await bsAPI.getCollaborationMapsFromUserID(58338, 20, "2021-10-20T15:30:00+00:00");

Response

Refer to responses page. Response data type: SearchResponse

getLatestMaps()

Returns the latest maps according to the filters.

Usage

Parameters	Type	Explanation	Limitations	Required	Default value
after	string	Return maps after this date. Format: YYYY-MM-DDTHH:MM:SS+00:00	Minimum year is 1970 and maximum is 9999.	no	null
before	string	Return maps before this date. Format: YYYY-MM-DDTHH:MM:SS+00:00	Minimum year is 1970 and maximum is 9999.	no	null
automapper	boolean	Include maps that are created using an auto mapper.		no	null
pageSize	number	Number of maps to return.	Cannot be more than 9 characters.	no	20
sort	string	Sort maps by sort options. (FIRST_PUBLISHED, UPDATED, LAST_PUBLISHED, CREATED, CURATED)	Must be one of the provided sort options.	no	null

Returns

Status	Status type	Type	Explanation	Related parameter
invalidautomapper	error	string	Returns when automapper is not a boolean.	automapper
invalidbeforedate	error	string	Returns when before date isn't in the correct format.	before
invalidafterdate	error	string	Returns when after date isn't in the correct format.	after
invalidpagesize	error	string	Returns when pageSize is not a number.	pageSize
toolongpagesize	error	string	Returns when pageSize is longer than 9 characters.	pageSize
invalidsort	error	string	Returns when sort is not one of the valid 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	boolean	Returns when no maps are found.
true	success	boolean	Returns when maps had been found.

Example

Usage

var response = await bsAPI.getLatestMaps("2021-10-20T15:30:00+00:00", "2022-10-20T15:30:00+00:00", false, 20, "FIRST_PUBLISHED");

Response

Refer to responses page. Response data type: SearchResponse

getMapsByPlayCount()

Returns maps by play count. (Not currently tracked according to the api docs.)

Usage

Parameters	Type	Explanation	Limitations	Required	Default value
page	number	Page of the returned maps.	Cannot be more than 18 characters.	no	0

Returns

Status	Status type	Type	Explanation	Related parameter
invalidpage	error	string	Returns when page is not a number.	page
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 maps are found on the current page.
true	success	boolean	Returns when maps had been found on the current page.

Example

Usage

var response = await bsAPI.getMapsByPlayCount(0);

Response

Refer to responses page. Response data type: SearchResponse