Variable default`Const`

default: { beatmaps: { get: ((oauthAccessToken: Readonly<OAuthAccessToken>, beatmapId: number) => Promise<Beatmap>); lookup: ((oauthAccessToken: Readonly<OAuthAccessToken>, checksum?: string, filename?: string, id?: number) => Promise<Beatmap>); scores: { users: ((oauthAccessToken: Readonly<OAuthAccessToken>, beatmapId: number, userId: number, mode?: GameMode, mods?: readonly string[]) => Promise<BeatmapUserScore>) } }; beatmapsets: { get: ((oauthAccessToken: Readonly<OAuthAccessToken>, beatmapsetId: number) => Promise<Beatmapset>); search: ((oauthAccessToken: Readonly<OAuthAccessToken>, query: string, onlyBeatmapsetsWithLeaderboard?: boolean) => Promise<BeatmapsetSearchResult>) }; oauth: { authorizationCodeGrant: ((clientId: number, clientSecret: string, redirectUri: string, code: string) => Promise<OAuthAccessTokenWithRefreshTokenResponse>); authorizeRedirectUrlGenerator: ((clientId: number, redirectUri: string, scopes?: readonly OAuthAuthorizeScope[], state?: string) => string); clientCredentialsGrant: ((clientId: number, clientSecret: string) => Promise<OAuthAccessTokenResponse>); refreshTokenGrant: ((clientId: number, clientSecret: string, redirectUri: string, refreshToken: string) => Promise<OAuthAccessTokenWithRefreshTokenResponse>) }; search: { user: ((oauthAccessToken: Readonly<OAuthAccessToken>, query: string, page?: number) => Promise<SearchResult<UserEndpointSearchUser>>); wikiPage: ((oauthAccessToken: Readonly<OAuthAccessToken>, query: string, page?: number) => Promise<SearchResult<WikiPage>>) }; users: { get: ((oauthAccessToken: Readonly<OAuthAccessToken>, userIdOrName: string | number, mode?: GameMode) => Promise<UserEndpointGet>); me: ((oauthAccessToken: Readonly<OAuthAccessToken>, mode?: GameMode) => Promise<UserEndpointMe>); recentActivity: ((oauthAccessToken: Readonly<OAuthAccessToken>, userId: number, limit?: number, offset?: number) => Promise<Events[]>); scores: ((oauthAccessToken: Readonly<OAuthAccessToken>, userId: number, type?: ScoresType, mode?: GameMode, limit?: number, offset?: number, includeFails?: boolean) => Promise<Score[]>) } } = ...

A collection of all supported osu!api v2 endpoints.

Type declaration

beatmaps: { get: ((oauthAccessToken: Readonly<OAuthAccessToken>, beatmapId: number) => Promise<Beatmap>); lookup: ((oauthAccessToken: Readonly<OAuthAccessToken>, checksum?: string, filename?: string, id?: number) => Promise<Beatmap>); scores: { users: ((oauthAccessToken: Readonly<OAuthAccessToken>, beatmapId: number, userId: number, mode?: GameMode, mods?: readonly string[]) => Promise<BeatmapUserScore>) } }
- get: ((oauthAccessToken: Readonly<OAuthAccessToken>, beatmapId: number) => Promise<Beatmap>)
  - - (oauthAccessToken: Readonly<OAuthAccessToken>, beatmapId: number): Promise<Beatmap>
    - Parameters
      
      oauthAccessToken: Readonly<OAuthAccessToken>
      
      beatmapId: number
      Returns Promise<Beatmap>
- lookup: ((oauthAccessToken: Readonly<OAuthAccessToken>, checksum?: string, filename?: string, id?: number) => Promise<Beatmap>)
  - - (oauthAccessToken: Readonly<OAuthAccessToken>, checksum?: string, filename?: string, id?: number): Promise<Beatmap>
    - Parameters
      
      oauthAccessToken: Readonly<OAuthAccessToken>
      
      Optional checksum: string
      
      Optional filename: string
      
      Optional id: number
      Returns Promise<Beatmap>
- scores: { users: ((oauthAccessToken: Readonly<OAuthAccessToken>, beatmapId: number, userId: number, mode?: GameMode, mods?: readonly string[]) => Promise<BeatmapUserScore>) }
  - users: ((oauthAccessToken: Readonly<OAuthAccessToken>, beatmapId: number, userId: number, mode?: GameMode, mods?: readonly string[]) => Promise<BeatmapUserScore>)
    - - (oauthAccessToken: Readonly<OAuthAccessToken>, beatmapId: number, userId: number, mode?: GameMode, mods?: readonly string[]): Promise<BeatmapUserScore>
      - Parameters
        
        oauthAccessToken: Readonly<OAuthAccessToken>
        
        beatmapId: number
        
        userId: number
        
        Optional mode: GameMode
        
        Optional mods: readonly string[]
        
        Returns Promise<BeatmapUserScore>
beatmapsets: { get: ((oauthAccessToken: Readonly<OAuthAccessToken>, beatmapsetId: number) => Promise<Beatmapset>); search: ((oauthAccessToken: Readonly<OAuthAccessToken>, query: string, onlyBeatmapsetsWithLeaderboard?: boolean) => Promise<BeatmapsetSearchResult>) }
- get: ((oauthAccessToken: Readonly<OAuthAccessToken>, beatmapsetId: number) => Promise<Beatmapset>)
  - - (oauthAccessToken: Readonly<OAuthAccessToken>, beatmapsetId: number): Promise<Beatmapset>
    - Parameters
      
      oauthAccessToken: Readonly<OAuthAccessToken>
      
      beatmapsetId: number
      Returns Promise<Beatmapset>
- search: ((oauthAccessToken: Readonly<OAuthAccessToken>, query: string, onlyBeatmapsetsWithLeaderboard?: boolean) => Promise<BeatmapsetSearchResult>)
  - - (oauthAccessToken: Readonly<OAuthAccessToken>, query: string, onlyBeatmapsetsWithLeaderboard?: boolean): Promise<BeatmapsetSearchResult>
    - Parameters
      
      oauthAccessToken: Readonly<OAuthAccessToken>
      
      query: string
      
      onlyBeatmapsetsWithLeaderboard: boolean = true
      Returns Promise<BeatmapsetSearchResult>
oauth: { authorizationCodeGrant: ((clientId: number, clientSecret: string, redirectUri: string, code: string) => Promise<OAuthAccessTokenWithRefreshTokenResponse>); authorizeRedirectUrlGenerator: ((clientId: number, redirectUri: string, scopes?: readonly OAuthAuthorizeScope[], state?: string) => string); clientCredentialsGrant: ((clientId: number, clientSecret: string) => Promise<OAuthAccessTokenResponse>); refreshTokenGrant: ((clientId: number, clientSecret: string, redirectUri: string, refreshToken: string) => Promise<OAuthAccessTokenWithRefreshTokenResponse>) }
- authorizationCodeGrant: ((clientId: number, clientSecret: string, redirectUri: string, code: string) => Promise<OAuthAccessTokenWithRefreshTokenResponse>)
  - - (clientId: number, clientSecret: string, redirectUri: string, code: string): Promise<OAuthAccessTokenWithRefreshTokenResponse>
    - Exchange the received code after successful authorization (via the authorizeRedirectUrlGenerator created redirect URI) for an access token that also contains a refresh token.
      
      Returns
      Successful requests will be issued an access token.
      
      Example
      import osuApiV2 from "osu-api-v2" const receivedCode = "fsjdkfndskjfndsjkfnsdkjfnsdkfns" const oAuthAccessTokenWithRefreshToken = await osuApiV2.oauth.authorizationCodeGrant( 1234, "sjasnfkjdsnfjkasnfköjsdnfösdkfnsf", "http://localhost:8888", receivedCode, )
      
      (Source)
      Parameters
      
      clientId: number
      
      The client ID of your application.
      
      clientSecret: string
      
      The client secret of your application.
      
      redirectUri: string
      
      The URL in your application where users will be sent after authorization.
      
      code: string
      
      The code you received.
      Returns Promise<OAuthAccessTokenWithRefreshTokenResponse>
- authorizeRedirectUrlGenerator: ((clientId: number, redirectUri: string, scopes?: readonly OAuthAuthorizeScope[], state?: string) => string)
  - - (clientId: number, redirectUri: string, scopes?: readonly OAuthAuthorizeScope[], state?: string): string
    - To obtain an access token, you must first get an authorization code that is created when a user grants permissions to your application. To request permission from the user, they should be redirected to an authorize URL that is created with this method.
      
      If the user accepts your request, they will be redirected back to your site with a temporary single-use code contained in the URL parameter. If a state value was provided in the previous request, it will be returned here.
      
      Returns
      The authorize redirect URI which opens the authorization dialogue.
      
      Example
      import osuApiV2, { OAuthAuthorizeScope } from "osu-api-v2" import open from "open" const authorizeUrl = osuApiV2.oauth.authorizeRedirectUrlGenerator( 1234, "http://localhost:8888", [OAuthAuthorizeScope.PUBLIC, OAuthAuthorizeScope.IDENTIFY], ) await open(authorizeUrl)
      
      Example
      https://osu.ppy.sh/oauth/authorize?client_id=1234&redirect_uri=http://localhost:8888&scope=public%20identify&response_type=code
      
      (Source)
      Parameters
      
      clientId: number
      
      The Client ID you received when you registered.
      
      redirectUri: string
      
      The URL in your application where users will be sent after authorization. This must match the registered Application Callback URL exactly.
      
      Optional scopes: readonly OAuthAuthorizeScope[]
      
      A list of scopes.
      
      Optional state: string
      
      Data that will be returned when a temporary code is issued. It can be used to provide a token for protecting against cross-site request forgery attacks.
      Returns string
- clientCredentialsGrant: ((clientId: number, clientSecret: string) => Promise<OAuthAccessTokenResponse>)
  - - (clientId: number, clientSecret: string): Promise<OAuthAccessTokenResponse>
    - The client credential flow provides a way for developers to get access tokens that do not have associated user permissions; as such, these tokens are considered as guest users.
      
      Returns
      Successful requests will be issued an access token.
      
      Example
      const oAuthAccessToken = await osuApiV2.oauth.clientCredentialsGrant( 1234, "fsdjfhdsjklfhlsjdkhfldskfsdf", )
      
      (Source)
      Parameters
      
      clientId: number
      
      The Client ID you received when you registered.
      
      clientSecret: string
      
      The client secret of your application.
      Returns Promise<OAuthAccessTokenResponse>
- refreshTokenGrant: ((clientId: number, clientSecret: string, redirectUri: string, refreshToken: string) => Promise<OAuthAccessTokenWithRefreshTokenResponse>)
  - - (clientId: number, clientSecret: string, redirectUri: string, refreshToken: string): Promise<OAuthAccessTokenWithRefreshTokenResponse>
    - Request a new refresh token.
      
      Upon successful response this will invalidate your current refresh token and needs to be updated with the in the response contained new refresh token.
      
      Example
      import osuApiV2 from "osu-api-v2" const oAuthAccessTokenWithRefreshToken = await osuApiV2.oauth.refreshTokenGrant( 1234, "sjasnfkjdsnfjkasnfköjsdnfösdkfnsf", "http://localhost:8888", "sdadasdsadasdasdafdsfsfsfsfsfsads", )
      Parameters
      
      clientId: number
      
      The Client ID you received when you registered.
      
      clientSecret: string
      
      The client secret of your application.
      
      redirectUri: string
      
      The redirect URI of your application.
      
      refreshToken: string
      
      The current granted refresh token (from either this method or from authorizationCodeGrant).
      Returns Promise<OAuthAccessTokenWithRefreshTokenResponse>

search: { user: ((oauthAccessToken: Readonly<OAuthAccessToken>, query: string, page?: number) => Promise<SearchResult<UserEndpointSearchUser>>); wikiPage: ((oauthAccessToken: Readonly<OAuthAccessToken>, query: string, page?: number) => Promise<SearchResult<WikiPage>>) }

user: ((oauthAccessToken: Readonly<OAuthAccessToken>, query: string, page?: number) => Promise<SearchResult<UserEndpointSearchUser>>)

(oauthAccessToken: Readonly<OAuthAccessToken>, query: string, page?: number): Promise<SearchResult<UserEndpointSearchUser>>

Search for a user using a query.

Example

import osuApiV2 from "osu-api-v2"

const user = await osuApiV2.search.user(
    oauthAccessToken,
    "niklas616",
)

{
    "data": [
        {
            "avatar_url": "https://a.ppy.sh/18508852?1658605422.png",
            "country_code": "DE",
            "default_group": "default",
            "id": 18508852,
            "is_active": true,
            "is_bot": false,
            "is_deleted": false,
            "is_online": false,
            "is_supporter": false,
            "last_visit": null,
            "pm_friends_only": false,
            "profile_colour": null,
            "username": "niklas616"
        }
    ],
    "total": 1
}

Example

import osuApiV2 from "osu-api-v2"

const user = await osuApiV2.search.user(
    oauthAccessToken,
    "Ooi",
    2,
)

(trimmed long data attributes: user.data)

{
    "data": [
        {
            "avatar_url": "https://osu.ppy.sh/images/layout/avatar-guest.png",
            "country_code": "XX",
            "default_group": "default",
            "id": 7914105,
            "is_active": false,
            "is_bot": false,
            "is_deleted": false,
            "is_online": false,
            "is_supporter": false,
            "last_visit": "2016-02-10T07:28:41+00:00",
            "pm_friends_only": false,
            "profile_colour": null,
            "username": "Ooi Chee Yong"
        },
        {
            "avatar_url": "https://osu.ppy.sh/images/layout/avatar-guest.png",
            "country_code": "MY",
            "default_group": "default",
            "id": 17515891,
            "is_active": false,
            "is_bot": false,
            "is_deleted": false,
            "is_online": false,
            "is_supporter": false,
            "last_visit": "2020-08-19T14:56:52+00:00",
            "pm_friends_only": false,
            "profile_colour": null,
            "username": "OOI JUN WEI"
        },
        {
            "avatar_url": "https://a.ppy.sh/14648144?1560926555.jpeg",
            "country_code": "MY",
            "default_group": "default",
            "id": 14648144,
            "is_active": false,
            "is_bot": false,
            "is_deleted": false,
            "is_online": false,
            "is_supporter": false,
            "last_visit": "2022-06-20T09:45:34+00:00",
            "pm_friends_only": false,
            "profile_colour": null,
            "username": "ooi kai xian"
        }
    ],
    "total": 308
}

(Source)

Parameters

oauthAccessToken: Readonly<OAuthAccessToken>

The OAuth Access token.
query: string

Search keyword.
Optional page: number

Search result page.

Returns Promise<SearchResult<UserEndpointSearchUser>>

wikiPage: ((oauthAccessToken: Readonly<OAuthAccessToken>, query: string, page?: number) => Promise<SearchResult<WikiPage>>)

(oauthAccessToken: Readonly<OAuthAccessToken>, query: string, page?: number): Promise<SearchResult<WikiPage>>

Search for a wiki page using a query.

Example

import osuApiV2 from "osu-api-v2"

const user = await osuApiV2.search.wikiPage(
    oauthAccessToken,
    "sotarks",
)

(trimmed long data attributes: data, data.available_locales, data.markdown, data.tags)

{
    "data": [
        {
            "available_locales": [
                "en",
                "fr",
                "ja"
            ],
            "layout": "markdown_page",
            "locale": "en",
            "markdown": "# Staff log 2018\n\n## January\n\n...",
            "path": "People/The_Team/Staff_Log/2018",
            "subtitle": "Staff log",
            "tags": [],
            "title": "Staff log 2018"
        },
        {
            "available_locales": [
                "en"
            ],
            "layout": "markdown_page",
            "locale": "en",
            "markdown": "---\ntags:\n  - o!ET2021\n  - o!E...",
            "path": "Tournaments/o!ET/2021",
            "subtitle": "osu! European Tournament",
            "tags": [
                "o!ET2021",
                "o!ET"
            ],
            "title": "osu! European Tournament 2021"
        },
        {
            "available_locales": [
                "en",
                "fr"
            ],
            "layout": "markdown_page",
            "locale": "en",
            "markdown": "---\ntags:\n  - FBC\n  - Mapping\n...",
            "path": "Contests/FBC",
            "subtitle": "Contests",
            "tags": [
                "FBC",
                "Mapping"
            ],
            "title": "French Beatmapping Contest"
        }
    ],
    "total": 40
}

Example

import osuApiV2 from "osu-api-v2"

const user = await osuApiV2.search.wikiPage(
    oauthAccessToken,
    "sotarks",
    2,
)

{
    "data": [],
    "total": 40
}

(Source)

Parameters

oauthAccessToken: Readonly<OAuthAccessToken>

The OAuth Access token.
query: string

Search keyword.
Optional page: number

Search result page.

Returns Promise<SearchResult<WikiPage>>

users: { get: ((oauthAccessToken: Readonly<OAuthAccessToken>, userIdOrName: string | number, mode?: GameMode) => Promise<UserEndpointGet>); me: ((oauthAccessToken: Readonly<OAuthAccessToken>, mode?: GameMode) => Promise<UserEndpointMe>); recentActivity: ((oauthAccessToken: Readonly<OAuthAccessToken>, userId: number, limit?: number, offset?: number) => Promise<Events[]>); scores: ((oauthAccessToken: Readonly<OAuthAccessToken>, userId: number, type?: ScoresType, mode?: GameMode, limit?: number, offset?: number, includeFails?: boolean) => Promise<Score[]>) }

get: ((oauthAccessToken: Readonly<OAuthAccessToken>, userIdOrName: string | number, mode?: GameMode) => Promise<UserEndpointGet>)

(oauthAccessToken: Readonly<OAuthAccessToken>, userIdOrName: string | number, mode?: GameMode): Promise<UserEndpointGet>

Get a user by their ID or username.

Throws

If the web request fails like for example when no user was found with the provided user ID a OsuApiV2WebRequestError is being thrown. This also happens if a restricted user is fetched.

Throws

If the web request returns an unexpected type or no user but doesn't throw a web request error a OsuApiV2Error is being thrown.

Example

import osuApiV2 from "osu-api-v2"

const user = await osuApiV2.users.get(
    oauthAccessToken,
    9096716,
)

(trimmed long data attributes: monthly_playcounts, page.html, page.raw, rank_history.data, replays_watched_counts, user_achievements)

(removed deprecated keys: cover_url, rankHistory, ranked_and_approved_beatmapset_count, unranked_beatmapset_count)

{
    "avatar_url": "https://a.ppy.sh/9096716?1657853808.jpeg",
    "country_code": "US",
    "default_group": "default",
    "id": 9096716,
    "is_active": true,
    "is_bot": false,
    "is_deleted": false,
    "is_online": false,
    "is_supporter": true,
    "last_visit": null,
    "pm_friends_only": false,
    "profile_colour": null,
    "username": "Ooi",
    "discord": "LazyBoy#8455",
    "has_supported": true,
    "interests": null,
    "join_date": "2016-10-07T23:01:42+00:00",
    "kudosu": {
        "total": 0,
        "available": 0
    },
    "location": null,
    "max_blocks": 100,
    "max_friends": 500,
    "occupation": null,
    "playmode": "osu",
    "playstyle": [
        "keyboard",
        "tablet"
    ],
    "post_count": 0,
    "profile_order": [
        "me",
        "recent_activity",
        "top_ranks",
        "historical",
        "medals",
        "beatmaps",
        "kudosu"
    ],
    "title": null,
    "title_url": null,
    "twitter": "ImLazyBoy_",
    "website": "https://www.twitch.tv/ImLazyBoy",
    "country": {
        "code": "US",
        "name": "United States"
    },
    "cover": {
        "custom_url": "https://assets.ppy.sh/user-profile-covers/9096716/81232f717e3edbd0e804e203ba99e71fed85b7110e91e676287a6e08eb5f7899.png",
        "url": "https://assets.ppy.sh/user-profile-covers/9096716/81232f717e3edbd0e804e203ba99e71fed85b7110e91e676287a6e08eb5f7899.png",
        "id": null
    },
    "account_history": [],
    "active_tournament_banner": null,
    "badges": [],
    "beatmap_playcounts_count": 12295,
    "comments_count": 0,
    "favourite_beatmapset_count": 47,
    "follower_count": 472,
    "graveyard_beatmapset_count": 1,
    "groups": [],
    "guest_beatmapset_count": 0,
    "loved_beatmapset_count": 0,
    "mapping_follower_count": 4,
    "monthly_playcounts": [
        {
            "start_date": "2016-10-01",
            "count": 166
        },
        {
            "start_date": "2016-11-01",
            "count": 594
        },
        {
            "start_date": "2016-12-01",
            "count": 2146
        }
    ],
    "page": {
        "html": "<div class='bbcode bbcode--pro...",
        "raw": "[notice][centre][url=https://w..."
    },
    "pending_beatmapset_count": 0,
    "previous_usernames": [
        "yoB yzaL"
    ],
    "ranked_beatmapset_count": 0,
    "replays_watched_counts": [
        {
            "start_date": "2017-01-01",
            "count": 2
        },
        {
            "start_date": "2017-02-01",
            "count": 1
        },
        {
            "start_date": "2017-04-01",
            "count": 1
        }
    ],
    "scores_best_count": 100,
    "scores_first_count": 2,
    "scores_pinned_count": 8,
    "scores_recent_count": 12,
    "statistics": {
        "level": {
            "current": 102,
            "progress": 88
        },
        "global_rank": 1319,
        "pp": 10776,
        "ranked_score": 71934348389,
        "hit_accuracy": 98.9572,
        "play_count": 117034,
        "play_time": 6893600,
        "total_score": 315143525692,
        "total_hits": 29197994,
        "maximum_combo": 7757,
        "replays_watched_by_others": 2771,
        "is_ranked": true,
        "grade_counts": {
            "ss": 554,
            "ssh": 180,
            "s": 1810,
            "sh": 564,
            "a": 2856
        },
        "country_rank": 252,
        "rank": {
            "country": 252
        }
    },
    "support_level": 3,
    "user_achievements": [
        {
            "achieved_at": "2022-09-12T17:53:36+00:00",
            "achievement_id": 285
        },
        {
            "achieved_at": "2022-09-11T23:42:50+00:00",
            "achievement_id": 287
        },
        {
            "achieved_at": "2022-08-18T21:18:49+00:00",
            "achievement_id": 276
        }
    ],
    "rank_history": {
        "mode": "osu",
        "data": [
            1390,
            1391,
            1392
        ]
    }
}

Example

import osuApiV2 from "osu-api-v2"

const user = await osuApiV2.users.get(
    oauthAccessToken,
    "Ooi",
)

(trimmed long data attributes: monthly_playcounts, page.html, page.raw, rank_history.data, replays_watched_counts, user_achievements)

(removed deprecated keys: cover_url, rankHistory, ranked_and_approved_beatmapset_count, unranked_beatmapset_count)

{
    "avatar_url": "https://a.ppy.sh/9096716?1657853808.jpeg",
    "country_code": "US",
    "default_group": "default",
    "id": 9096716,
    "is_active": true,
    "is_bot": false,
    "is_deleted": false,
    "is_online": false,
    "is_supporter": true,
    "last_visit": null,
    "pm_friends_only": false,
    "profile_colour": null,
    "username": "Ooi",
    "discord": "LazyBoy#8455",
    "has_supported": true,
    "interests": null,
    "join_date": "2016-10-07T23:01:42+00:00",
    "kudosu": {
        "total": 0,
        "available": 0
    },
    "location": null,
    "max_blocks": 100,
    "max_friends": 500,
    "occupation": null,
    "playmode": "osu",
    "playstyle": [
        "keyboard",
        "tablet"
    ],
    "post_count": 0,
    "profile_order": [
        "me",
        "recent_activity",
        "top_ranks",
        "historical",
        "medals",
        "beatmaps",
        "kudosu"
    ],
    "title": null,
    "title_url": null,
    "twitter": "ImLazyBoy_",
    "website": "https://www.twitch.tv/ImLazyBoy",
    "country": {
        "code": "US",
        "name": "United States"
    },
    "cover": {
        "custom_url": "https://assets.ppy.sh/user-profile-covers/9096716/81232f717e3edbd0e804e203ba99e71fed85b7110e91e676287a6e08eb5f7899.png",
        "url": "https://assets.ppy.sh/user-profile-covers/9096716/81232f717e3edbd0e804e203ba99e71fed85b7110e91e676287a6e08eb5f7899.png",
        "id": null
    },
    "account_history": [],
    "active_tournament_banner": null,
    "badges": [],
    "beatmap_playcounts_count": 12295,
    "comments_count": 0,
    "favourite_beatmapset_count": 47,
    "follower_count": 472,
    "graveyard_beatmapset_count": 1,
    "groups": [],
    "guest_beatmapset_count": 0,
    "loved_beatmapset_count": 0,
    "mapping_follower_count": 4,
    "monthly_playcounts": [
        {
            "start_date": "2016-10-01",
            "count": 166
        },
        {
            "start_date": "2016-11-01",
            "count": 594
        },
        {
            "start_date": "2016-12-01",
            "count": 2146
        }
    ],
    "page": {
        "html": "<div class='bbcode bbcode--pro...",
        "raw": "[notice][centre][url=https://w..."
    },
    "pending_beatmapset_count": 0,
    "previous_usernames": [
        "yoB yzaL"
    ],
    "ranked_beatmapset_count": 0,
    "replays_watched_counts": [
        {
            "start_date": "2017-01-01",
            "count": 2
        },
        {
            "start_date": "2017-02-01",
            "count": 1
        },
        {
            "start_date": "2017-04-01",
            "count": 1
        }
    ],
    "scores_best_count": 100,
    "scores_first_count": 2,
    "scores_pinned_count": 8,
    "scores_recent_count": 12,
    "statistics": {
        "level": {
            "current": 102,
            "progress": 88
        },
        "global_rank": 1319,
        "pp": 10776,
        "ranked_score": 71934348389,
        "hit_accuracy": 98.9572,
        "play_count": 117034,
        "play_time": 6893600,
        "total_score": 315143525692,
        "total_hits": 29197994,
        "maximum_combo": 7757,
        "replays_watched_by_others": 2771,
        "is_ranked": true,
        "grade_counts": {
            "ss": 554,
            "ssh": 180,
            "s": 1810,
            "sh": 564,
            "a": 2856
        },
        "country_rank": 252,
        "rank": {
            "country": 252
        }
    },
    "support_level": 3,
    "user_achievements": [
        {
            "achieved_at": "2022-09-12T17:53:36+00:00",
            "achievement_id": 285
        },
        {
            "achieved_at": "2022-09-11T23:42:50+00:00",
            "achievement_id": 287
        },
        {
            "achieved_at": "2022-08-18T21:18:49+00:00",
            "achievement_id": 276
        }
    ],
    "rank_history": {
        "mode": "osu",
        "data": [
            1390,
            1391,
            1392
        ]
    }
}

(Source)

Parameters

oauthAccessToken: Readonly<OAuthAccessToken>

The OAuth Access token.
userIdOrName: string | number

Either the osu! user name or ID of the user to get.
Optional mode: GameMode

Per default (ranking) statistics are returned regarding the default game mode of the user, to request statistics of the user regarding a specific game mode this argument can be supplied.

Returns Promise<UserEndpointGet>

me: ((oauthAccessToken: Readonly<OAuthAccessToken>, mode?: GameMode) => Promise<UserEndpointMe>)
- - (oauthAccessToken: Readonly<OAuthAccessToken>, mode?: GameMode): Promise<UserEndpointMe>
  - Similar to get but with authenticated user (token owner) as user id.
    
    You need to have the IDENTIFY scope to use this endpoint.
    
    Example
```
import osuApiV2 from "osu-api-v2"

const user = await osuApiV2.users.me(
    oauthAccessToken,
)
```
    (Source)
    Parameters
    - oauthAccessToken: Readonly<OAuthAccessToken>
      
      The OAuth Access token.
    - Optional mode: GameMode
      
      Per default (ranking) statistics are returned regarding the default game mode of the user, to request statistics of the user regarding a specific game mode this argument can be supplied.
    Returns Promise<UserEndpointMe>

recentActivity: ((oauthAccessToken: Readonly<OAuthAccessToken>, userId: number, limit?: number, offset?: number) => Promise<Events[]>)

(oauthAccessToken: Readonly<OAuthAccessToken>, userId: number, limit?: number, offset?: number): Promise<Events[]>

Get a list of recent activity events of a user.

Throws

If the web request fails like for example when no user was found with the provided user ID a OsuApiV2WebRequestError is being thrown.

Example

import osuApiV2 from "osu-api-v2"

const user = await osuApiV2.users.recentActivity(
    oauthAccessToken,
    9096716,
    20,
    1,
)

(trimmed long data attributes: [])

[
    {
        "created_at": "2022-09-26T02:03:14+00:00",
        "createdAt": "2022-09-26T02:03:14+00:00",
        "id": 744711020,
        "type": "rank",
        "scoreRank": "A",
        "rank": 415,
        "mode": "osu",
        "beatmap": {
            "title": "Ata - Euphoria [Ultimate Power]",
            "url": "/b/1861487?m=0"
        },
        "user": {
            "username": "Ooi",
            "url": "/u/9096716"
        }
    },
    {
        "created_at": "2022-09-26T01:43:55+00:00",
        "createdAt": "2022-09-26T01:43:55+00:00",
        "id": 744709051,
        "type": "rank",
        "scoreRank": "B",
        "rank": 16,
        "mode": "osu",
        "beatmap": {
            "title": "La priere - Evo [Rei's Lancer EVO 9 Insane]",
            "url": "/b/3682960?m=0"
        },
        "user": {
            "username": "Ooi",
            "url": "/u/9096716"
        }
    },
    {
        "created_at": "2022-09-26T01:16:39+00:00",
        "createdAt": "2022-09-26T01:16:39+00:00",
        "id": 744706544,
        "type": "userSupportAgain",
        "user": {
            "username": "Ooi",
            "url": "/users/9096716"
        }
    }
]

Example

import osuApiV2 from "osu-api-v2"

const user = await osuApiV2.users.recentActivity(
    oauthAccessToken,
    2927048,
    10,
)

(trimmed long data attributes: [])

[
    {
        "created_at": "2022-09-26T09:05:43+00:00",
        "createdAt": "2022-09-26T09:05:43+00:00",
        "id": 744749086,
        "type": "rank",
        "scoreRank": "X",
        "rank": 74,
        "mode": "osu",
        "beatmap": {
            "title": "Rish feat. Choko - Tanaka [Hard]",
            "url": "/b/3348062?m=0"
        },
        "user": {
            "username": "EEEEEEEEEEEEEEE",
            "url": "/u/2927048"
        }
    },
    {
        "created_at": "2022-09-26T09:03:58+00:00",
        "createdAt": "2022-09-26T09:03:58+00:00",
        "id": 744748898,
        "type": "rank",
        "scoreRank": "S",
        "rank": 68,
        "mode": "osu",
        "beatmap": {
            "title": "Chicala Lpis - Blackest Luxury Car [ponbot's Hard]",
            "url": "/b/3348018?m=0"
        },
        "user": {
            "username": "EEEEEEEEEEEEEEE",
            "url": "/u/2927048"
        }
    },
    {
        "created_at": "2022-09-26T09:02:19+00:00",
        "createdAt": "2022-09-26T09:02:19+00:00",
        "id": 744748732,
        "type": "rank",
        "scoreRank": "S",
        "rank": 67,
        "mode": "osu",
        "beatmap": {
            "title": "Mirani, lIlBOI, GroovyRoom - Can't Slow Me Down [Asaiga's Hard]",
            "url": "/b/3493323?m=0"
        },
        "user": {
            "username": "EEEEEEEEEEEEEEE",
            "url": "/u/2927048"
        }
    }
]

(Source)

Parameters

oauthAccessToken: Readonly<OAuthAccessToken>

The OAuth Access token.
userId: number

The osu! user ID of the account from which the recent activity should be fetched.
Optional limit: number

Maximum number of results.
Optional offset: number

Result offset for pagination.

Returns Promise<Events[]>

scores: ((oauthAccessToken: Readonly<OAuthAccessToken>, userId: number, type?: ScoresType, mode?: GameMode, limit?: number, offset?: number, includeFails?: boolean) => Promise<Score[]>)

(oauthAccessToken: Readonly<OAuthAccessToken>, userId: number, type?: ScoresType, mode?: GameMode, limit?: number, offset?: number, includeFails?: boolean): Promise<Score[]>

Get a list of a type of scores (ScoresType) of a user.

Throws

If the web request fails like for example when no user was found with the provided user ID a OsuApiV2WebRequestError is being thrown.

Example

import osuApiV2, { GameMode, ScoresType } from "osu-api-v2"

const user = await osuApiV2.users.scores(
    oauthAccessToken,
    9096716,
    ScoresType.BEST,
    GameMode.OSU_STANDARD,
    2,
    1,
)

[
    {
        "accuracy": 0.9888783719829626,
        "best_id": 4275918471,
        "created_at": "2022-09-21T08:26:25+00:00",
        "id": 4275918471,
        "max_combo": 2500,
        "mode": "osu",
        "mode_int": 0,
        "mods": [],
        "passed": true,
        "perfect": true,
        "pp": 611.796,
        "rank": "S",
        "replay": true,
        "score": 156021430,
        "statistics": {
            "count_100": 34,
            "count_300": 2078,
            "count_50": 1,
            "count_geki": 250,
            "count_katu": 21,
            "count_miss": 0
        },
        "type": "score_best_osu",
        "user_id": 9096716,
        "current_user_attributes": {
            "pin": null
        },
        "beatmap": {
            "beatmapset_id": 1781620,
            "difficulty_rating": 7.32,
            "id": 3648544,
            "mode": "osu",
            "status": "ranked",
            "total_length": 287,
            "user_id": 14729352,
            "version": "Relentless Heartache",
            "accuracy": 9.5,
            "ar": 9.7,
            "bpm": 178,
            "convert": false,
            "count_circles": 1842,
            "count_sliders": 270,
            "count_spinners": 1,
            "cs": 4.3,
            "deleted_at": null,
            "drain": 5.2,
            "hit_length": 263,
            "is_scoreable": true,
            "last_updated": "2022-08-18T19:40:08+00:00",
            "mode_int": 0,
            "passcount": 3241,
            "playcount": 123661,
            "ranked": 1,
            "url": "https://osu.ppy.sh/beatmaps/3648544",
            "checksum": "77602792f51ad200b9e8bfcd5edbc1f9"
        },
        "beatmapset": {
            "artist": "Fellowship",
            "artist_unicode": "Fellowship",
            "covers": {
                "cover": "https://assets.ppy.sh/beatmaps/1781620/covers/cover.jpg?1660851627",
                "cover@2x": "https://assets.ppy.sh/beatmaps/1781620/covers/cover@2x.jpg?1660851627",
                "card": "https://assets.ppy.sh/beatmaps/1781620/covers/card.jpg?1660851627",
                "card@2x": "https://assets.ppy.sh/beatmaps/1781620/covers/card@2x.jpg?1660851627",
                "list": "https://assets.ppy.sh/beatmaps/1781620/covers/list.jpg?1660851627",
                "list@2x": "https://assets.ppy.sh/beatmaps/1781620/covers/list@2x.jpg?1660851627",
                "slimcover": "https://assets.ppy.sh/beatmaps/1781620/covers/slimcover.jpg?1660851627",
                "slimcover@2x": "https://assets.ppy.sh/beatmaps/1781620/covers/slimcover@2x.jpg?1660851627"
            },
            "creator": "nebuwua",
            "favourite_count": 811,
            "hype": null,
            "id": 1781620,
            "nsfw": false,
            "offset": 0,
            "play_count": 769108,
            "preview_url": "//b.ppy.sh/preview/1781620.mp3",
            "source": "",
            "spotlight": false,
            "status": "ranked",
            "title": "Glory Days",
            "title_unicode": "Glory Days",
            "track_id": null,
            "user_id": 14729352,
            "video": false
        },
        "user": {
            "avatar_url": "https://a.ppy.sh/9096716?1657853808.jpeg",
            "country_code": "US",
            "default_group": "default",
            "id": 9096716,
            "is_active": true,
            "is_bot": false,
            "is_deleted": false,
            "is_online": false,
            "is_supporter": true,
            "last_visit": null,
            "pm_friends_only": false,
            "profile_colour": null,
            "username": "Ooi"
        },
        "weight": {
            "percentage": 95,
            "pp": 581.2062
        }
    },
    {
        "accuracy": 0.9983416252072969,
        "best_id": 3903542366,
        "created_at": "2021-10-11T02:08:16+00:00",
        "id": 3903542366,
        "max_combo": 1851,
        "mode": "osu",
        "mode_int": 0,
        "mods": [],
        "passed": true,
        "perfect": false,
        "pp": 579.294,
        "rank": "S",
        "replay": true,
        "score": 83573770,
        "statistics": {
            "count_100": 4,
            "count_300": 1604,
            "count_50": 0,
            "count_geki": 274,
            "count_katu": 4,
            "count_miss": 0
        },
        "type": "score_best_osu",
        "user_id": 9096716,
        "current_user_attributes": {
            "pin": null
        },
        "beatmap": {
            "beatmapset_id": 1008679,
            "difficulty_rating": 7.56,
            "id": 2111505,
            "mode": "osu",
            "status": "ranked",
            "total_length": 335,
            "user_id": 5522589,
            "version": "Sojourn Collab",
            "accuracy": 9.5,
            "ar": 9.8,
            "bpm": 188,
            "convert": false,
            "count_circles": 1146,
            "count_sliders": 459,
            "count_spinners": 3,
            "cs": 4.3,
            "deleted_at": null,
            "drain": 6,
            "hit_length": 315,
            "is_scoreable": true,
            "last_updated": "2019-09-21T16:15:11+00:00",
            "mode_int": 0,
            "passcount": 8730,
            "playcount": 218529,
            "ranked": 1,
            "url": "https://osu.ppy.sh/beatmaps/2111505",
            "checksum": "07ee6b0d4dc53ba3a2bfbb3ce0625706"
        },
        "beatmapset": {
            "artist": "VINXIS",
            "artist_unicode": "VINXIS",
            "covers": {
                "cover": "https://assets.ppy.sh/beatmaps/1008679/covers/cover.jpg?1645778100",
                "cover@2x": "https://assets.ppy.sh/beatmaps/1008679/covers/cover@2x.jpg?1645778100",
                "card": "https://assets.ppy.sh/beatmaps/1008679/covers/card.jpg?1645778100",
                "card@2x": "https://assets.ppy.sh/beatmaps/1008679/covers/card@2x.jpg?1645778100",
                "list": "https://assets.ppy.sh/beatmaps/1008679/covers/list.jpg?1645778100",
                "list@2x": "https://assets.ppy.sh/beatmaps/1008679/covers/list@2x.jpg?1645778100",
                "slimcover": "https://assets.ppy.sh/beatmaps/1008679/covers/slimcover.jpg?1645778100",
                "slimcover@2x": "https://assets.ppy.sh/beatmaps/1008679/covers/slimcover@2x.jpg?1645778100"
            },
            "creator": "Chanci",
            "favourite_count": 157,
            "hype": null,
            "id": 1008679,
            "nsfw": false,
            "offset": 0,
            "play_count": 218529,
            "preview_url": "//b.ppy.sh/preview/1008679.mp3",
            "source": "",
            "spotlight": false,
            "status": "ranked",
            "title": "Sidetracked Day",
            "title_unicode": "Sidetracked Day",
            "track_id": 433,
            "user_id": 10510791,
            "video": false
        },
        "user": {
            "avatar_url": "https://a.ppy.sh/9096716?1657853808.jpeg",
            "country_code": "US",
            "default_group": "default",
            "id": 9096716,
            "is_active": true,
            "is_bot": false,
            "is_deleted": false,
            "is_online": false,
            "is_supporter": true,
            "last_visit": null,
            "pm_friends_only": false,
            "profile_colour": null,
            "username": "Ooi"
        },
        "weight": {
            "percentage": 90.25,
            "pp": 522.812835
        }
    }
]

Example

import osuApiV2, { GameMode, ScoresType } from "osu-api-v2"

const user = await osuApiV2.users.scores(
    oauthAccessToken,
    2927048,
    ScoresType.RECENT,
    GameMode.OSU_STANDARD,
    2,
    0,
    true,
)

(Source)

Parameters

oauthAccessToken: Readonly<OAuthAccessToken>

The OAuth Access token.
userId: number

The osu! user ID of the account from which scores should be fetched.
type: ScoresType = ScoresType.BEST

The type of scores that should be fetched.
mode: GameMode = GameMode.OSU_STANDARD

The game mode for which the scores should be fetched.
Optional limit: number

Maximum number of results.
Optional offset: number

Result offset for pagination.
Optional includeFails: boolean

Only for recent scores, include scores of failed plays. Is off per default.

Variable defaultConst

Type declaration

get: ((oauthAccessToken: Readonly<OAuthAccessToken>, beatmapId: number) => Promise<Beatmap>)

Parameters

oauthAccessToken: Readonly<OAuthAccessToken>

beatmapId: number

Returns Promise<Beatmap>

lookup: ((oauthAccessToken: Readonly<OAuthAccessToken>, checksum?: string, filename?: string, id?: number) => Promise<Beatmap>)

Parameters

oauthAccessToken: Readonly<OAuthAccessToken>

Optional checksum: string

Optional filename: string

Optional id: number

Returns Promise<Beatmap>

scores: { users: ((oauthAccessToken: Readonly<OAuthAccessToken>, beatmapId: number, userId: number, mode?: GameMode, mods?: readonly string[]) => Promise<BeatmapUserScore>) }

users: ((oauthAccessToken: Readonly<OAuthAccessToken>, beatmapId: number, userId: number, mode?: GameMode, mods?: readonly string[]) => Promise<BeatmapUserScore>)

Parameters

oauthAccessToken: Readonly<OAuthAccessToken>

beatmapId: number

userId: number

Optional mode: GameMode

Optional mods: readonly string[]

Returns Promise<BeatmapUserScore>

beatmapsets: { get: ((oauthAccessToken: Readonly<OAuthAccessToken>, beatmapsetId: number) => Promise<Beatmapset>); search: ((oauthAccessToken: Readonly<OAuthAccessToken>, query: string, onlyBeatmapsetsWithLeaderboard?: boolean) => Promise<BeatmapsetSearchResult>) }

get: ((oauthAccessToken: Readonly<OAuthAccessToken>, beatmapsetId: number) => Promise<Beatmapset>)

Parameters

oauthAccessToken: Readonly<OAuthAccessToken>

beatmapsetId: number

Returns Promise<Beatmapset>

search: ((oauthAccessToken: Readonly<OAuthAccessToken>, query: string, onlyBeatmapsetsWithLeaderboard?: boolean) => Promise<BeatmapsetSearchResult>)

Parameters

oauthAccessToken: Readonly<OAuthAccessToken>

query: string

onlyBeatmapsetsWithLeaderboard: boolean = true

Returns Promise<BeatmapsetSearchResult>

authorizationCodeGrant: ((clientId: number, clientSecret: string, redirectUri: string, code: string) => Promise<OAuthAccessTokenWithRefreshTokenResponse>)

Returns

Example

Parameters

clientId: number

clientSecret: string

redirectUri: string

code: string

Returns Promise<OAuthAccessTokenWithRefreshTokenResponse>

authorizeRedirectUrlGenerator: ((clientId: number, redirectUri: string, scopes?: readonly OAuthAuthorizeScope[], state?: string) => string)

Returns

Example

Example

Parameters

clientId: number

redirectUri: string

Optional scopes: readonly OAuthAuthorizeScope[]

Optional state: string

Returns string

clientCredentialsGrant: ((clientId: number, clientSecret: string) => Promise<OAuthAccessTokenResponse>)

Returns

Example

Parameters

clientId: number

clientSecret: string

Returns Promise<OAuthAccessTokenResponse>

refreshTokenGrant: ((clientId: number, clientSecret: string, redirectUri: string, refreshToken: string) => Promise<OAuthAccessTokenWithRefreshTokenResponse>)

Example

Parameters

clientId: number

clientSecret: string

redirectUri: string

refreshToken: string

Returns Promise<OAuthAccessTokenWithRefreshTokenResponse>

search: { user: ((oauthAccessToken: Readonly<OAuthAccessToken>, query: string, page?: number) => Promise<SearchResult<UserEndpointSearchUser>>); wikiPage: ((oauthAccessToken: Readonly<OAuthAccessToken>, query: string, page?: number) => Promise<SearchResult<WikiPage>>) }

user: ((oauthAccessToken: Readonly<OAuthAccessToken>, query: string, page?: number) => Promise<SearchResult<UserEndpointSearchUser>>)

Example

Example

Parameters

oauthAccessToken: Readonly<OAuthAccessToken>

query: string

Optional page: number

Returns Promise<SearchResult<UserEndpointSearchUser>>

wikiPage: ((oauthAccessToken: Readonly<OAuthAccessToken>, query: string, page?: number) => Promise<SearchResult<WikiPage>>)

Example

Variable default`Const`

`Optional` checksum: string

`Optional` filename: string

`Optional` id: number

`Optional` mode: GameMode

`Optional` mods: readonly string[]

`Optional` scopes: readonly OAuthAuthorizeScope[]

`Optional` state: string

`Optional` page: number

`Optional` page: number

`Optional` mode: GameMode

`Optional` mode: GameMode

`Optional` limit: number

`Optional` offset: number

`Optional` limit: number

`Optional` offset: number

`Optional` includeFails: boolean