API Reference¶
OsuApi¶
-
class
osuapi.osu.
OsuApi
(key, *, connector)¶ osu! api client.
Parameters: - key – The osu! api key used for authorization.
- connector – The osuapi connector used for making requests. The library comes with
two implementations,
osuapi.connectors.AHConnector
for using aiohttp, andosuapi.connectors.ReqConnector
for using requests.
-
get_user
(username, *, mode=<OsuMode.osu: 0>, event_days=31)¶ Get a user profile.
Parameters: - username (str or int) – A str representing the user’s username, or an int representing the user’s id.
- mode (
osuapi.enums.OsuMode
) – The osu! game mode for which to look up. Defaults to osu!standard. - event_days (int) – The number of days in the past to look for events. Defaults to 31 (the maximum).
-
get_user_best
(username, *, mode=<OsuMode.osu: 0>, limit=50)¶ Get a user’s best scores.
Parameters: - username (str or int) – A str representing the user’s username, or an int representing the user’s id.
- mode (
osuapi.enums.OsuMode
) – The osu! game mode for which to look up. Defaults to osu!standard. - limit – The maximum number of results to return. Defaults to 50, maximum 100.
-
get_user_recent
(username, *, mode=<OsuMode.osu: 0>, limit=10)¶ Get a user’s most recent scores, within the last 24 hours.
Parameters: - username (str or int) – A str representing the user’s username, or an int representing the user’s id.
- mode (
osuapi.enums.OsuMode
) – The osu! game mode for which to look up. Defaults to osu!standard. - limit – The maximum number of results to return. Defaults to 10, maximum 50.
-
get_scores
(beatmap_id, *, username=None, mode=<OsuMode.osu: 0>, mods=None, limit=50)¶ Get the top scores for a given beatmap.
Parameters: - beatmap_id – Individual Beatmap ID to lookup.
- username (str or int) – A str representing the user’s username, or an int representing the user’s id. If specified, restricts returned scores to the specified user.
- mode (
osuapi.enums.OsuMode
) – The osu! game mode for which to look up. Defaults to osu!standard. - mods (
osuap:class:`osuapi.enums.OsuMod
) – If specified, restricts returned scores to the specified mods. - limit – Number of results to return. Defaults to 50, maximum 100.
-
get_beatmaps
(*, since=None, beatmapset_id=None, beatmap_id=None, username=None, mode=None, include_converted=False, beatmap_hash=None, limit=500)¶ Get beatmaps.
Parameters: - since (datetime) – If specified, restrict results to beatmaps ranked after this date.
- beatmapset_id – If specified, restrict results to a specific beatmap set.
- beatmap_id – If specified, restrict results to a specific beatmap.
- username (str or int) – A str representing the user’s username, or an int representing the user’s id. If specified, restrict results to a specific user.
- mode (
osuapi.enums.OsuMode
) – If specified, restrict results to a specific osu! game mode. - include_converted (bool) – Whether or not to include autoconverts. Defaults to false.
- beatmap_hash – If specified, restricts results to a specific beatmap hash.
- limit – Number of results to return. Defaults to 500, maximum 500.
-
get_match
(match_id)¶ Get a multiplayer match.
Parameters: match_id – The ID of the match to retrieve. This is the ID that you see in a online multiplayer match summary. This does not correspond the in-game game ID.
Built-in Connectors¶
Build in connectors.
Connectors have to implement process_request.
-
class
osuapi.connectors.
AHConnector
(sess=None, loop=None)¶ Connector implementation using aiohttp.
-
process_request
(endpoint, data, type_, retries=5)¶ Make and process the request.
This can raise anything aiohttp.get() can raise, or osuapi.HTTPError if we run out of retries.
Parameters: - endpoint (str) – The HTTP endpoint to make a request to
- data (dict) – The parameters for making the HTTP request
- type (type) – A converter to which to pass the response json and return.
- retries (int) – Maximum number of times to try request.
-
-
class
osuapi.connectors.
ReqConnector
(sess=None)¶ Connector implementation using requests.
-
process_request
(endpoint, data, type_, retries=5)¶ Make and process the request.
This can raise anything requests.get() can raise, or osuapi.HTTPError if we run out of retries.
Parameters: - endpoint (str) – The HTTP endpoint to make a request to
- data (dict) – The parameters for making the HTTP request
- type (type) – A converter to which to pass the response json and return.
- retries (int) – Maximum number of times to try request.
-
Model¶
Different classes to parse dicts/lists returned from json into meaningful data objects.
-
class
osuapi.model.
Score
(dct)¶ Abstract class representing a score.
-
score
¶ int – The score value
-
maxcombo
¶ int – Largest combo achieved
-
count50
¶ int – Number of “50” hits. In catch: number of “droplet” hits
-
count100
¶ int – Number of “100” hits In taiko: number of “good” hits In catch: number of “drop” hits
-
count300
¶ int – Number of “300” hits In taiko: number of “great” hits In catch: number of “fruit” hits
-
countmiss
¶ int – Number of misses In catch: number of “fruit” or “drop” misses
-
countkatu
¶ int – Number of “katu” sections (only 100s and 300s) In taiko: number of “double good” hits In mania: number of “200” hits In catch: number of “droplet” misses
-
countgeki
¶ int – Number of “geki” sections (only 300s) In taiko: number of “double great” hits In mania: number of “rainbow 300” hits
-
perfect
¶ bool – If the play is a full combo (maxcombo is maximal)
-
user_id
¶ int – ID of user who played.
-
rank
¶ str – Letter rank achieved
See also
-
accuracy
(mode: osuapi.enums.OsuMode)¶ Calculated accuracy.
See also
-
-
class
osuapi.model.
TeamScore
(dct)¶ Class representing a score in a multiplayer team game.
See
Score
-
slot
¶ int – Which multiplayer slot the player was in.
-
team
¶ int – Which multiplayer team the player was in.
-
passed
¶ bool – If the score is passing.
See also
-
-
class
osuapi.model.
RecentScore
(dct)¶ Class representing a recent score.
See
Score
-
beatmap_id
¶ int – Beatmap the score is for.
-
enabled_mods
¶ osuapi.enums.OsuMod
– Enabled modifiers
-
date
¶ datetime – When the score was played.
See also
-
-
class
osuapi.model.
SoloScore
(dct)¶ Class representing a score in singleplayer.
See
Score
-
beatmap_id
¶ int – Beatmap the score is for.
-
pp
¶ Optional[float] – How much PP the score is worth, or None if not eligible for PP.
-
enabled_mods
¶ osuapi.enums.OsuMod
– Enabled modifiers
-
date
¶ datetime – When the score was played.
See also
-
-
class
osuapi.model.
BeatmapScore
(dct)¶ Class representing a score attached to a beatmap.
See
Score
-
username
¶ str – Name of user.
-
pp
¶ Optional[float] – How much PP the score is worth, or None if not eligible for PP.
-
enabled_mods
¶ osuapi.enums.OsuMod
– Enabled modifiers
-
date
¶ datetime – When the score was played.
-
score_id
¶ int – ID of score.
-
replay_available
¶ bool – If a replay is available.
See also
-
-
class
osuapi.model.
UserEvent
(dct)¶ Class representing individual user events.
-
display_html
¶ str – HTML for the event.
-
beatmap_id
¶ Optional[int] – Beatmap this event occured on, or None if the event has no beatmap.
-
beatmapset_id
¶ Optional[int] – Beatmap set this event occured on, or None if the event has no beatmap.
-
date
¶ datetime – Date this event occured.
-
epicfactor
¶ int – Epic factor (between 1 and 32)
-
-
class
osuapi.model.
User
(dct)¶ Class representing a user.
-
user_id
¶ int – User’s unique identifier.
-
username
¶ str – User’s name.
-
count300
¶ int – Career total of “300” hits.
-
count100
¶ int – Career total of “100” hits.
-
count50
¶ int – Career total of “50” hits.
-
playcount
¶ int – Career total play count.
-
ranked_score
¶ int – Total sum of the best scores from all the ranked beatmaps played online.
-
total_score
¶ int – Total sum of all scores on ranked beatmaps, including failed trails.
-
pp_rank
¶ int – Global ranking place.
-
level
¶ float – User’s level
-
pp_raw
¶ float – User’s performance points
-
total_seconds_played
¶ int – User’s total playtime
-
accuracy
¶ float – Weighted average of accuracy on top plays.
-
count_rank_ssh
¶ int – Career total of SSH ranks.
-
count_rank_ss
¶ int – Career total of SS ranks.
-
count_rank_sh
¶ int – Career total of SH ranks.
-
count_rank_s
¶ int – Career total of S ranks.
-
count_rank_a
¶ int – Career total of A ranks.
-
country
¶ str – Country the user is registered to.
-
pp_country_rank
¶ int – Country ranking place.
-
events
¶ list[dict] – Information about recent “interesting” events.
See also
-
-
class
osuapi.model.
Beatmap
(dct)¶ Class representing a beatmap
-
approved
¶ BeatmapStatus – Whether or not the map has been ranked.
-
approved_date
¶ Optional[datetime] – When the beatmap was ranked, or None.
-
last_update
¶ datetime – Last time the map was updated.
-
artist
¶ str – Music metadata.
-
beatmap_id
¶ int – Unique identifier for beatmap.
-
beatmapset_id
¶ int – Unique identifier for set this beatmap belongs to.
-
bpm
¶ float – Speed of map in beats per minute.
-
creator
¶ str – Username of map creator.
-
creator_id
¶ int – ID of the map creator.
-
difficultyrating
¶ float – Star rating of a map.
-
diff_size
¶ float – Circle Size. (CS)
-
diff_overall
¶ float – Overall Difficulty. (OD)
-
diff_approach
¶ float – Approach rate. (AR)
-
diff_drain
¶ float – Health Drain (HP)
-
hit_length
¶ int – Playable time in seconds. (Drain time)
-
source
¶ str – Source of the music
-
genre_id
¶ osuapi.enums.BeatmapGenre
– Genre of the music.
-
language_id
¶ osuapi.enums.BeatmapLanguage
– Language of the music.
-
title
¶ str – Title of the song.
-
total_length
¶ int – Total song length in seconds.
-
version
¶ str – Difficulty name.
-
file_md5
¶ str – md5 hash of map.
-
mode
¶ osuapi.enums.OsuMode
– Game mode for the map.
str – Space delimited tags for the map.
-
favourite_count
¶ int – Number of users that have favorited this map.
-
playcount
¶ int – Number of times this map has been played (including fails)/
-
passcount
¶ int – Number of times this map has been passed.
-
max_combo
¶ Optional[int] – Maximum possible combo.
See also
-
-
class
osuapi.model.
MatchMetadata
(dct)¶ Class representing info about a match.
-
match_id
¶ int – Unique identifier for this match.
-
name
¶ str – Name of the match when it was first created.
-
start_time
¶ datetime – When the match was created.
-
end_time
¶ Optional[datetime] – When the match was ended, or None.
-
-
class
osuapi.model.
Game
(dct)¶ Class representing an individual multiplayer game.
-
game_id
¶ int – Unique identifier for this game.
-
start_time
¶ datetime – When the game started.
-
end_time
¶ datetime – When the game ended.
-
beatmap_id
¶ int – Beatmap played.
-
play_mode
¶ osuapi.enums.OsuMode
– Game mode.
-
match_type
¶ Not really sure…
-
scoring_type
¶ osuapi.enums.ScoringType
– Scoring type of game.
-
team_type
¶ osuapi.enums.TeamType
– Team type of the game.
-
mods
¶ osuapi.enums.OsuMod
– Modifiers enabled for all players.
-
-
class
osuapi.model.
Match
(dct)¶ Class representing a match’s info and collection of games.
Enums¶
Enums and flags.
-
class
osuapi.enums.
OsuMode
¶ Enum representing osu! game mode.
-
osu
= 0¶
-
taiko
= 1¶
-
ctb
= 2¶
-
mania
= 3¶
-
-
class
osuapi.enums.
OsuMod
(value, shortname='')¶ Bitwise Flags representing osu! mods.
Notes
# Check if a given flag is set. OsuMod.HardRock in flags # Check if a given flag is not set. OsuMod.HardRock not in flags # Check if all given flags are set. flags.contains_all(OsuMod.Hidden | OsuMod.HardRock) # Check if any of given flags are set. OsuMod.keyMod in flags
-
NoMod
= <OsuMod NoMod>¶
-
NoFail
= <OsuMod NoFail>¶
-
Easy
= <OsuMod Easy>¶
-
NoVideo
= <OsuMod NoVideo>¶
-
Hidden
= <OsuMod Hidden>¶
-
HardRock
= <OsuMod HardRock>¶
-
SuddenDeath
= <OsuMod SuddenDeath>¶
-
DoubleTime
= <OsuMod DoubleTime>¶
-
Relax
= <OsuMod Relax>¶
-
HalfTime
= <OsuMod HalfTime>¶
-
Nightcore
= <OsuMod Nightcore>¶
-
Flashlight
= <OsuMod Flashlight>¶
-
Autoplay
= <OsuMod Autoplay>¶
-
SpunOut
= <OsuMod SpunOut>¶
-
Autopilot
= <OsuMod Autopilot>¶
-
Perfect
= <OsuMod Perfect>¶
-
Key4
= <OsuMod Key4>¶
-
Key5
= <OsuMod Key5>¶
-
Key6
= <OsuMod Key6>¶
-
Key7
= <OsuMod Key7>¶
-
Key8
= <OsuMod Key8>¶
-
FadeIn
= <OsuMod FadeIn>¶
-
Random
= <OsuMod Random>¶
-
LastMod
= <OsuMod LastMod>¶
-
Key9
= <OsuMod Key9>¶
-
Key10
= <OsuMod Key10>¶
-
Key1
= <OsuMod Key1>¶
-
Key3
= <OsuMod Key3>¶
-
Key2
= <OsuMod Key2>¶
-
shortname
¶ The initialism representing this mod. (e.g. HDHR)
-
longname
¶ The long name representing this mod. (e.g. Hidden DoubleTime)
-
FreeModAllowed
= <OsuMod NoFail | Easy | Hidden | HardRock | SuddenDeath | Relax | Flashlight | SpunOut | Autopilot | Key4 | Key5 | Key6 | Key7 | Key8 | FadeIn>¶
-
keyMod
= <OsuMod Key4 | Key5 | Key6 | Key7 | Key8>¶
-
-
class
osuapi.enums.
BeatmapStatus
¶ Enum representing the ranked status of a beatmap.
See also
-
graveyard
= -2¶
-
wip
= -1¶
-
pending
= 0¶
-
ranked
= 1¶
-
approved
= 2¶
-
qualified
= 3¶
-
loved
= 4¶
-
-
class
osuapi.enums.
BeatmapGenre
¶ Enum represeting the genre of a beatmap.
-
any
= 0¶
-
unspecified
= 1¶
-
video_game
= 2¶
-
anime
= 3¶
-
rock
= 4¶
-
pop
= 5¶
-
other
= 6¶
-
novelty
= 7¶
-
hip_hop
= 9¶
-
electronic
= 10¶
-
-
class
osuapi.enums.
BeatmapLanguage
¶ Enum represeting the language of a beatmap.
-
any
= 0¶
-
other
= 1¶
-
english
= 2¶
-
japanese
= 3¶
-
chinese
= 4¶
-
instrumental
= 5¶
-
korean
= 6¶
-
french
= 7¶
-
german
= 8¶
-
swedish
= 9¶
-
spanish
= 10¶
-
italian
= 11¶
-