The module is promise based, and uses osu!API v2. To use API you need to register your app here, just scroll down to set up oAuth applications. You will need the client id and secret code. Only the most frequently used, stable API endpoints are available! If something is wrong, you can report it on GitHub.

Usage

Current stable release (1.x) requires at least Node.js 15.0.0.

Install with npm

$ npm i @rascm/osu

Load module, and request token in ESM:

import osu from '@rasm/osu';
const auth = new osu.Authentication("Your client id here", "Your secret key here");
const token = await auth.client(); // Return {"access_token" : "your access token here", "token_type" : "Bearer", "expires_in" : 86400} or {"error" : "reason here", "response" : "returned object from API"}

Load module, and request token in Common JS:

const osu = require('@rascm/osu');
const auth = new osu.Authentication("Your client id here", "Your secret key here");
const token = auth.client();
token.then(access_token => {
	// access_token = {"access_token" : "your access token here", "token_type" : "Bearer", "expires_in" : 86400}  or {"error" : "reason here", "response" : "returned object from API"}
});
token.catch(error => {
    // error = Reject reason
});

Available Endpoints

Beatmapsets:

Beatmap and beatmapset listing, filtering, search, beatmapset events, and information fetching about beatmaps.

Scores:

Retrieve player results, view map rankings, retrieve matches, information about scores.

Users:

Detailed profiles of players, kudosu informations, player history...

Detailed information of functions

class Authentication

Generate access tokens, make authorization url.

| Parameter | type | required | | -------------- | :-----: | :------: | | $client_id | integer | yes | | $client_secret | string | yes |

Functions:

client($params): return Promise

Client authentication provides an access token for developers that does not involve a user.

| Parameter | type | required | | --------- | :----: | :------: | | $params | object | no |

Default value:

| object key | type | required | default value | | ------------- | :-----: | :------: | ------------------------- | | client_id | integer | no | $client_id from class | | client_secret | string | no | $client_secret from class | | grant_type | string | no | client_credentials | | scope | string | no | public |

authorization($params): return Promise

Generate token for user.

| Parameter | type | required | | --------- | :----: | :------: | | $params | object | yes |

Default value:

| object key | type | required | default value | | ------------- | :-----: | :------: | ------------------------- | | client_id | integer | no | $client_id from class | | client_secret | string | no | $client_secret from class | | grant_type | string | no | authorization_code | | redirect_uri | string | yes | | | code | string | yes | |

url($searchParams): return String

Generate a url address for the user, where they can request a temporary code to generate a token for themselves.

| Parameter | type | required | | --------- | :----: | :------: | | $params | object | yes |

Default value:

| object key | type | required | default value | | ------------- | :-----: | :------: | --------------------- | | client_id | integer | no | $client_id from class | | response_type | string | no | code | | scope | string | no | identify public | | redirect_uri | string | yes | | | code | string | yes | |

class Beatmapsets extends ParseToken

Information about beatmaps, beatmapsets.

| Parameter | type | required | | ------------- | :----: | :------: | | $access_token | object | yes |

Default value:

| object key | type | required | default value | | ------------ | :-----: | :------: | ------------- | | token_type | string | yes | | | access_token | string | yes | | | expires_in | integer | yes | |

Functions:

events($searchParams): return Promise

Get recent beatmapset events.

| Parameter | type | required | | ------------- | ------ | -------- | | $searchParams | object | no |

Default value:

| object key | type | required | default value | | ---------- | :----: | :------: | ------------------------------------------------------------ | | user | string | no | | | types | array | no | ['qualify', 'rank', 'nominate', 'disqualify', 'nomination_reset', 'remove_from_loved', 'approve'] | | min_date | string | no | | | max_date | string | no | |

• user: user whose events you want to view.
• types: List only the specified events. Each event must be entered in an array. Accepted values: nominate, qualify, rank, love, nomination_reset, nomination_reset_received, disqualify, remove_from_loved, kudosu_gain, kudosu_lost, genre_edit, language_edit, nsfw_toggle, issue_resolve, issue_reopen, beatmap_owner_change, kudosu_allow, kudosu_deny, approve, kudosu_recalculate, discussion_delete, discussion_restore, discussion_post_delete, discussion_post_restore
• min_date: Start date, which cannot be greater than or equal to end date. Only accepted YYYY-MM-dd format.
• max_date: End date, which cannot be less than or equal to start date. Only accepted YYYY-MM-dd format.

getBeatmap($beatmap_id): return Promise

Get information about beatmap with id.

| Parameter | type | required | | ----------- | ------- | -------- | | $beatmap_id | integer | yes |

getBeatmapset($beatmapset_id): return Promise

Get information about beatmapset with id.

| Parameter | type | required | | -------------- | ------- | -------- | | $beatmapset_id | integer | yes |

lookupBeatmap($searchParams): return Promise

Get beatmap information with id, filename, or checksum.

| Parameter | type | required | | ------------- | ------ | -------- | | $searchParams | object | yes |

filters:

At least one filter must be used

• checksum
• filename
• id

search($searchParams): return Promise

Search and filter beatmap by criteria.

| Parameter | type | required | | ------------- | ------ | -------- | | $searchParams | object | yes |

filters:

At least one filter must be used

| object key | type | default value | | -------------- | ------- | ------------- | | visual | string | | | featuredArtist | boolean | | | genre | string | | | language | string | | | mode | string | | | query | string | | | type | string | any |

• visual: Should it include a video, a storyboard or both? Accepted values: storyboard, video, both.
• featuredArtist: Search only the featured artists
• genre: Search only beatmaps in this genre. Accepted values: videogame, anime, rock, pop, other, novelty, hiphop, electronic, metal, classical, folk, jazz or unspecified.
• language: Search only beatmaps in this language. Accepted values: english, chinese, french, german, italian, japanese, korean, spanish, swedish, russian, polish, instrumental, unspecified or other.
• mode: Search in specified game mode. Accepted values: standard, taiko, fruits or mania
• query: You can enter the search terms.
• type: What kind of maps should it search for? Accepted values: ranked, loved, qualified, pending, graveyard or any

class Scores extends ParseToken

Information about beatmap scores and matches

| Parameter | type | required | | ------------- | :----: | :------: | | $access_token | object | yes |

Default value:

| object key | type | required | default value | | ------------ | :-----: | :------: | ------------- | | token_type | string | yes | | | access_token | string | yes | | | expires_in | integer | yes | |

Functions:

getBeatmapScore($beatmap_id, $user_id, $searchParams): return Promise

Get beatmap score from a user.

| Parameter | type | required | | ------------- | ------- | -------- | | $beatmap_id | integer | yes | | $user_id | integer | yes | | $searchParams | object | no |

$searchParams object:

• mode: Get score from specified game mode. Accepted values: fruits, mania, osu or taiko.

getInfo($score_id, $user_id, $mode): return Promise

Get information about score by id and mode.

| Parameter | type | required | | --------- | ------- | -------- | | $score_id | integer | yes | | $mode | string | yes |

• $mode: The mode associated with the score. Accepted values: standard, taiko, fruits, mania

getMatch($match_id): return Promise

Get information about match.

| Parameter | type | required | | --------- | ------- | -------- | | $match_id | integer | yes |

• $match_id: Unique identifier of the match

getMatches($searchParams): return Promise

List matches.

| Parameter | type | required | | ------------- | ------ | -------- | | $searchParams | object | no |

$searchParams object:

• limit: Number of matches per page Default: 20
• offset: Result offset for pagination. Default: 0

getUserScores($user_id, $type, $searchParams): return Promise

List matches.

| Parameter | type | required | | ------------- | ------- | -------- | | $user_id | integer | yes | | $type | string | no | | $searchParams | object | no |

$type: Types of results achieved. Accepted values: best, firsts or recent. Default: best

$searchParams object:

• limit: Number of scores per page Default: 20
• offset: Result offset for pagination. Default: 0

class Users extends ParseToken

Information about users.

| Parameter | type | required | | ------------- | :----: | :------: | | $access_token | object | yes |

Default value:

| object key | type | required | default value | | ------------ | :-----: | :------: | ------------- | | token_type | string | yes | | | access_token | string | yes | | | expires_in | integer | yes | |

Functions:

getBeatmaps($user_id, $type, $searchParams): return Promise

Get user beatmaps.

| Parameter | type | required | | ------------- | :-----: | :------: | | $user_id | integer | yes | | $type | string | no | | $searchParams | object | no |

$type: Beatmap types. Accepted values: favourite, most_played, pending, ranked, graveyard or loved

$searchParams object:

• limit: Number of beatmapsets per page Default: 20
• offset: Result offset for pagination. Default: 0

getKudosu($user_id, $searchParams): return Promise

Get user kudosu informations.

| Parameter | type | required | | ------------- | ------- | -------- | | $user_id | integer | yes | | $searchParams | object | no |

$searchParams object:

• limit: Number of beatmapsets per page Default: 20
• offset: Result offset for pagination. Default: 0

getMe($mode): return Promise Requires user authentication!

Get current authenticated user information.

| Parameter | type | required | | --------- | ------ | -------- | | $mode | string | no |

$mode: User default mode will be used if not specified. Accepted values: standard, taiko, fruits or mania

getUser($user_id, $mode, $by): return Promise

Get specified user profile.

| Parameter | type | required | | --------- | ---------------------------------------- | -------- | | $user_id | integer or string (depends on $by value) | yes | | $mode | string | no | | $by | string | no |

$mode: User default mode will be used if not specified. Accepted values: standard, taiko, fruits or mania

$by: If you want to search by username, change it to 'name'. Default value: id

recentActivity($user_id, $searchParams): return Promise

Get user recent activities.

| Parameter | type | required | | ------------- | ------- | -------- | | $user_id | integer | yes | | $searchParams | object | no |

$searchParams object:

• limit: Number of beatmapsets per page Default: 20
• offset: Result offset for pagination. Default: 0