Beatmaps

beatmap(self, beatmap_id=None, *, checksum=None, filename=None)

Get a beatmap from an id, checksum, or filename.

Parameters:

  • beatmap_id (int | BeatmapCompact | None) – The id of the beatmap.

  • checksum (str | None) – The md5 hash of the beatmap.

  • filename (str | None) – The filename of the beatmap.

Return type:

Beatmap

Notes

Combines the Get Beatmap and Lookup Beatmap endpoints.

beatmap_attributes(self, beatmap_id, *, mods=None, ruleset=None, ruleset_id=None)

Get the difficult attributes of a beatmap. Used for pp calculation.

Parameters:

  • beatmap_id (int) – The beatmap to get the difficulty attributes of.

  • mods (Mod | str | int | List[Mod | str | int] | None) – The mods to calculate difficulty attributes with.

  • ruleset (GameMode | str | None) – The ruleset (gamemode) to calculate difficulty attributes of.

  • ruleset_id (int | None) – Alternative parameter to ruleset which takes an integer (ruleset id) instead of a string (ruleset name).

Return type:

DifficultyAttributes

Notes

Implements the Get Beatmap Attributes endpoint.

beatmap_scores(self, beatmap_id, *, mode=None, mods=None, type=None, limit=None, legacy_only=None)

Get the top scores of a beatmap.

Parameters:

  • beatmap_id (int | BeatmapCompact) – The beatmap to get scores of.

  • mode (GameMode | str | None) – The mode to get scores of.

  • mods (Mod | str | int | List[Mod | str | int] | None) – Get the top scores set with exactly these mods, if passed.

  • type (RankingType | str | None) – How to order the scores. Defaults to ordering by score.

  • limit (int | None) – How many results to return. Defaults to 50. Must be between 1 and 100.

  • legacy_only (bool | None) – Whether to exclude lazer scores. Defaults to False.

Return type:

BeatmapScores

Notes

Implements the Get Beatmap Scores endpoint.

beatmap_user_score(self, beatmap_id, user_id, *, mode=None, mods=None, legacy_only=None)

Get a user’s best score on a beatmap. If you want to retrieve all scores, see beatmap_user_scores().

Parameters:

  • beatmap_id (int | BeatmapCompact) – The beatmap the score was set on.

  • user_id (int | UserCompact) – The user who set the score.

  • mode (GameMode | str | None) – The mode the scores were set on.

  • mods (Mod | str | int | List[Mod | str | int] | None) – The mods the score was set with.

  • legacy_only (bool | None) – Whether to exclude lazer scores. Defaults to False.

Return type:

BeatmapUserScore

Notes

Implements the User Beatmap Score endpoint.

beatmap_user_scores(self, beatmap_id, user_id, *, mode=None, legacy_only=None)

Get all of a user’s scores on a beatmap. If you only want the top user score, see beatmap_user_score().

Parameters:

  • beatmap_id (int | BeatmapCompact) – The beatmap the scores were set on.

  • user_id (int | UserCompact) – The user who set the scores.

  • mode (GameMode | str | None) – The mode the scores were set on.

  • legacy_only (bool | None) – Whether to exclude lazer scores. Defaults to False.

Return type:

List[Score]

Notes

Implements to User Beatmap Scores endpoint.

beatmaps(self, beatmap_ids)

Batch get beatmaps by id. If you only want to retrieve a single beatmap, or want to retrieve beatmaps by something other than id (eg checksum), see beatmap().

Parameters:

beatmap_ids (List[int | BeatmapCompact]) – The beatmaps to get.

Return type:

List[Beatmap]

Notes

Implements the Get Beatmaps endpoint.