LostPy/osu-: A Small Module To Get Informations With ... - GitHub

osu-api.py

A small package to get informations with osu!api. With this package you can choose the type of data in output (json, dict or dataframe). An api key is required to access the osu!api data!

Index

1. Global informations

2. Installation

3. Get api key

   • Terms of Use

4. Documentation

   • osu!api V1

     • get_beatmaps
     • get_user
     • get_scores
     • get_user_best
     • get_user_recent
     • get_match
     • get_replay

   • osu!api V2

   • Enumerate

Global informations

• Author: LostPy

• Version: 1.0

• License: MIT License

• Requirements:

  • Mandatory

    • Python 3.x
    • requests

  • Optionnal

    • pandas

• Api supported:

  • osu!api V1: YES
  • osu!api V2: Coming soon

• Utility link:

  • get a key
  • term of use for osu!api
  • osu!api V1
  • osu!api V2

Installation

To install this package, you can use the following command:

pip install git+https://github.com/LostPy/osu-api.py.git@main

To update the package, you can use: pip install git+https://github.com/LostPy/osu-api.py.git@main --upgrade

OR

pip install git+https://github.com/LostPy/osu-api.py.git@main -U

Get a api key

To get a api key, you can ask here. Before begining, check the terms of use of osu!api.

Terms of use

The terms of use of osu!api are:

Use the API for good. Don't overdo it. If in doubt, ask before (ab)using :). this section may expand as necessary.

Current rate limit is set at an insanely high 1200 requests per minute, with burst capability of up to 200 beyond that. If you require more, you probably fall into the above category of abuse. If you are doing more than 60 requests a minute, you should probably give peppy a yell.

Documentation

This documentation is structured by osu!api

osu!api V1

get_beatmaps

• Description: Function to get general beatmap information.

• Arguments: For more information, check osu!api.

Name	Type	Description	Default value
key	str	The api key to access at osu!api.
since	str	To return all beatmaps ranked or loved since this date. Must be a MySQL date. In UTC.	None (return all)
beatmapset_id	int	id of beatmapset to return.	None (return all)
beatmap_id	int	id of beatmap to return.	None (return all)
user	int or str	user id or username to return metadata from	None
type_	str	id or string to specify user type. By default, it's automatic recognition.	None
mode	int	Mode of beatmaps to return.	None (all game mode)
a	int	0 or 1. Specify whether converted beatmaps are included (0 = not included, 1 = included).	0
h	str	The beatmap hash. For more info: osu!api	None
limit	int	Amount of results.	500
mods	int	mods that applies to the beatmap requested. You can use the dictionnaty mods to get the id of mods	0 (all mods)
type_return	str	The type to return. Take 3 possibles values: dict, json, dataframe. To dataframe, the pandas package must be installed.	'dict'

• Return: The result of http request with the data form specify with type_return.

get_user

• Description: Function to get general user information.

• Arguments: For more information, check osu!api.

Name	Type	Description	Default value
key	str	The api key to access at osu!api.
user	int or str	user id or username to return metadata from
type_	str	id or string to specify user type. By default, it's automatic recognition.	None
mode	int	Mode of beatmaps to return.	0
event_days	int	Max number of days between now and last event date. Range of 1-31.	1
type_return	str	The type to return. Take 3 possibles values: dict, json, dataframe. To dataframe, the pandas package must be installed.	'dict'

• Return: The result of http request with the data form specify with type_return.

get_scores

• Description: Function to get information about the top 100 of a beatmap.

• Arguments: For more information, check osu!api.

Name	Type	Description	Default value
key	str	The api key to access at osu!api.
beatmap_id	int	id of beatmap.
user	int or str	user id or username to return metadata from	None
type_	str	id or string to specify user type. By default, it's automatic recognition.	None
mode	int	Mode of beatmaps to return.	0
mods	int	mods that applies to the score requested. You can use the dictionnaty mods to get the id of mods	0 (all mods)
limit	int	Amount of results. Between 1 & 100	50
type_return	str	The type to return. Take 3 possibles values: dict, json, dataframe. To dataframe, the pandas package must be installed.	'dict'

• Return: The result of http request with the data form specify with type_return.

get_user_best

• Description: Function to get general user information.

• Arguments: For more information, check osu!api.

Name	Type	Description	Default value
key	str	The api key to access at osu!api.
user	int or str	user id or username to return metadata from
mode	int	Mode of beatmaps to return.	0
limit	int	Amount of results. Between 1 & 100	10
type_	str	id or string to specify user type. By default, it's automatic recognition.	None
type_return	str	The type to return. Take 3 possibles values: dict, json, dataframe. To dataframe, the pandas package must be installed.	'dict'

• Return: The result of http request with the data form specify with type_return.

get_user_recent

• Description: Function to gets the user's ten most recent plays over the last 24 hours.

• Arguments: For more information, check osu!api.

Name	Type	Description	Default value
key	str	The api key to access at osu!api.
user	int or str	user id or username to return metadata from
mode	int	Mode of beatmaps to return.	0
limit	int	Amount of results. Between 1 & 50	10
type_	str	id or string to specify user type. By default, it's automatic recognition.	None
type_return	str	The type to return. Take 3 possibles values: dict, json, dataframe. To dataframe, the pandas package must be installed.	'dict'

• Return: The result of http request with the data form specify with type_return.

get_match

• Description: Function to gets information about multiplayer match.

• Arguments: For more information, check osu!api.

Name	Type	Description	Default value
key	str	The api key to access at osu!api.
match_id	int	Id of match to return.
type_return	str	The type to return. Take 3 possibles values: dict, json, dataframe. To dataframe, the pandas package must be installed.	'dict'

• Return: The result of http request with the data form specify with type_return.

get_replay

• Description: Function to gets the user's ten most recent plays over the last 24 hours.

• Arguments: For more information, check osu!api.

Name	Type	Description	Default value
key	str	The api key to access at osu!api.
beatmap_id	int	id of beatmap.
user	int or str	user id or username to return metadata from
mode	int	Mode of beatmaps to return.	None
score_id	int	id of score to return. May be passed instead of b and u.	None
type_	str	id or string to specify user type. By default, it's automatic recognition.	None
mods	int	mod or mods combination. You can use the dictionnaty mods to get the id of mods.	None

• Return: The result of http request with the data form specify with type_return.

osu!api V2

Coming soon...

Enumerate

Mods

A static class with mods.

Attributes of class

Mods.none = 0 Mods.no_fail = 1 Mods.easy = 2 Mods.touch_device = 4 Mods.hidden = 8 Mods.hard_rock = 16 Mods.sudden_death = 32 Mods.double_time = 64 Mods.relax = 128 Mods.half_time = 256 Mods.nightcore = 512 # Only set along with DoubleTime. i.e: NC only gives 576 Mods.flashlight = 1024 Mods.autoplay = 2048 Mods.spun_out = 4096 Mods.relax2 = 8192 # Autopilot Mods.perfect = 16384 # Only set along with SuddenDeath. i.e: PF only gives 16416 Mods.key4 = 32768 Mods.key5 = 65536 Mods.key6 = 131072 Mods.key7 = 262144 Mods.key8 = 524288 Mods.fade_in = 1048576 Mods.random = 2097152 Mods.cinema = 4194304 Mods.target = 8388608 Mods.key9 = 16777216 Mods.key_coop = 33554432 Mods.key1 = 67108864 Mods.key3 = 134217728 Mods.key2 = 268435456 Mods.score_v2 = 536870912 Mods.mirror = 1073741824

Static methods

• key_mod return Mods.key1 | Mods.key2 | Mods.key3 | Mods.key4 | Mods.key5 | Mods.key6 | Mods.key7 | Mods.key8 | Mods.key9 | Mods.key_coop

• free_mod_allowed return Mods.no_fail | Mods.easy | Mods.hidden | Mods.hard_rock | Mods.sudden_death | Mods.flashlight | Mods.fade_in | Mods.relax | Mods.relax2 | Mods.spun_out | Mods.key_mod()

• score_increase_mods return Mods.hidden | Mods.hard_rock | Mods.double_time | Mods.flashlight | Mods.fade_in

Index

1. Global informations

2. Installation

3. Get api key

   • Terms of Use

4. Documentation

   • osu!api V1

     • get_beatmaps
     • get_user
     • get_scores
     • get_user_best
     • get_user_recent
     • get_match
     • get_replay

   • osu!api V2

   • Enumerate