Class API

constructor

• new API(key: string, verbose?: "none" | "errors" | "all", server?: string): API

  Parameters

  • key: string

    Your API key, which you can get at https://osu.ppy.sh/p/api

  • verbose: "none" | "errors" | "all" = "none"

    (default none) Which events should be logged

  • server: string = "https://osu.ppy.sh/api/"

    (default https://osu.ppy.sh/api/) The server where the requests should be sent to

  Returns API

key

server

verbose

getBeatmap

• getBeatmap(
      beatmap: Beatmap | { beatmap_id: number },
      mods?: Mods[],
      gamemode?: Gamemodes,
  ): Promise<Beatmap>

  Look for and get a singular Beatmap with this!

  Parameters

  • beatmap: Beatmap | { beatmap_id: number }

    An Object with the ID of the difficulty/Beatmap of the beatmapset

  • mods: Mods[] = []

    An array of Mods to apply, defaults to an empty array

  • Optionalgamemode: Gamemodes

    The gamemode the beatmap is in (useful if you wanna convert, for example, an osu! map to taiko)

  Returns Promise<Beatmap>

  A Promise with a Beatmap

getBeatmaps

• getBeatmaps(
      limit: number,
      gamemode: { allow_converts?: boolean; gamemode: Gamemodes | "all" },
      beatmap?:
          | Beatmap
          | { beatmap_id?: number; beatmapset_id?: number; file_md5?: string },
      mods?: Mods[],
      set_owner?: User | { user_id?: number; username?: string },
      since?: Date,
  ): Promise<Beatmap[]>

  Look for and get Beatmaps with this! Throws an APIError if the array would be empty

  Parameters

  • limit: number

    The maximum number of Beatmaps there should be in the array, cannot exceed 500

  • gamemode: { allow_converts?: boolean; gamemode: Gamemodes | "all" }

    Filter in the beatmaps by the gamemode (unless "all"), but if allow_converts then instead convert if possible the beatmaps to that gamemode

  • Optionalbeatmap: Beatmap | { beatmap_id?: number; beatmapset_id?: number; file_md5?: string }

    Will look for its beatmapset_id (if undefined, its beatmap_id (if undefined, its file_md5))

  • mods: Mods[] = []

    An array of Mods to apply, defaults to an empty array

  • Optionalset_owner: User | { user_id?: number; username?: string }

    The User that owns the beatmapset

  • Optionalsince: Date

    Filters out any Beatmap of Category < 0, and any Beatmap with an approved_date older than what's given

  Returns Promise<Beatmap[]>

getBeatmapScores

• getBeatmapScores(
      limit: number,
      gamemode: Gamemodes,
      beatmap: Beatmap | { beatmap_id: number },
      user?: User | { user_id?: number; username?: string },
      mods?: Mods[],
  ): Promise<ScoreWithReplayavailablePp[]>

  Parameters

  • limit: number

    The maximum number of Scores to get, cannot exceed 100

  • gamemode: Gamemodes

    A number representing the Scores' Gamemode

  • beatmap: Beatmap | { beatmap_id: number }

    An Object with the ID of the difficulty/Beatmap of the beatmapset

  • Optionaluser: User | { user_id?: number; username?: string }

    The Scores' user, which is an Object with either a user_id or a username

  • mods: Mods[] = []

    An array of Mods to apply, defaults to an empty array

  Returns Promise<ScoreWithReplayavailablePp[]>

  A Promise with an array of Scores set on a beatmap

getMatch

• getMatch(id: number): Promise<Match>

  Parameters

  • id: number

    The ID of the Match

  Returns Promise<Match>

  A Promise with a Match

  Remarks

  If the API's server is set to https://ripple.moe/api, getMatch might not work as it's currently unsupported by Ripple, see https://docs.ripple.moe/docs/api/peppy

getReplay

• getReplay(
      gamemode: Gamemodes,
      replay: {
          score_id?: number;
          search?: {
              beatmap: Beatmap | { beatmap_id: number };
              mods: Mods[];
              user: User | { user_id?: number; username?: string };
          };
      },
  ): Promise<Replay>

  Specify the gamemode the score was set in, then say if you know the id of the Score OR if you know the score's User, Beatmap, and Mods

  Parameters

  • gamemode: Gamemodes

    A number representing the Gamemode the Score was set in

  • replay: {
        score_id?: number;
        search?: {
            beatmap: Beatmap | { beatmap_id: number };
            mods: Mods[];
            user: User | { user_id?: number; username?: string };
        };
    }

    An Object that contains a score with an id, or an Object that specifies info about the score (User, Beatmap, and Mods)

  Returns Promise<Replay>

  If possible, a Replay of that Score

  Remarks

  If the API's server is set to https://ripple.moe/api, getReplay might not work as it's currently unsupported by Ripple, see https://docs.ripple.moe/docs/api/peppy

getUser

• getUser(
      gamemode: Gamemodes,
      user: User | { user_id?: number; username?: string },
  ): Promise<User>

  Parameters

  • gamemode: Gamemodes

    The User's Gamemode

  • user: User | { user_id?: number; username?: string }

    An Object with either a user_id or a username (ignores username if user_id is specified)

  Returns Promise<User>

  A Promise with a User found with the search

getUserBestScores

• getUserBestScores(
      limit: number,
      gamemode: Gamemodes,
      user: User | { user_id?: number; username?: string },
  ): Promise<ScoreWithBeatmapidReplayavailablePp[]>

  Parameters

  • limit: number

    The maximum number of Scores to get, cannot exceed 100

  • gamemode: Gamemodes

    The User's Gamemode

  • user: User | { user_id?: number; username?: string }

    An Object with either a user_id or a username (user_id is preferred)

  Returns Promise<ScoreWithBeatmapidReplayavailablePp[]>

  A Promise with an array of Scores set by the User within the last 24 hours in a specific Gamemode

getUserRecentScores

• getUserRecentScores(
      limit: number,
      gamemode: Gamemodes,
      user: User | { user_id?: number; username?: string },
  ): Promise<ScoreWithBeatmapid[]>

  Parameters

  • limit: number

    The maximum number of Scores to get, cannot exceed 100

  • gamemode: Gamemodes

    The User's Gamemode

  • user: User | { user_id?: number; username?: string }

    An Object with either a user_id or a username (user_id is preferred)

  Returns Promise<ScoreWithBeatmapid[]>

  A Promise with an array of Scores set by the User within the last 24 hours in a specific Gamemode

request

• request(endpoint: string, parameters: string, number_try?: number): Promise<any>

  Make a custom request to the API server!

  Parameters

  • endpoint: string

    Basically the endpoint, what comes in the URL after api/

  • parameters: string

    The things to specify in the request, such as the beatmap_id when looking for a beatmap

  • number_try: number = 1

    How many attempts there's been to get the data

  Returns Promise<any>

  A Promise with the API's response