ossapi (documentation) ![PyPI version](https://camo.githubusercontent.com/ef2feeeecca98fcfeb4ea9268e00df052ee3427bde14b0cd0f0293804e1fb376/68747470733a2f2f62616467652e667572792e696f2f70792f6f73736170692e737667)
ossapi is the definitive python wrapper for the osu! api. ossapi has complete coverage of api v2 and api v1, and provides both sync (Ossapi
) and async (OssapiAsync
) versions for api v2.
If you need support or would like to contribute, feel free to ask in the #ossapi
channel of the circleguard discord.
To install:
pip install ossapi
# or, if you want to use OssapiAsync:
pip install ossapi[async]
To upgrade:
pip install -U ossapi
To get started, read the docs: https://tybug.github.io/ossapi/.
The docs have an in depth quickstart, but here's a super short version for api v2:
from ossapi import Ossapi
# create a new client at https://osu.ppy.sh/home/account/edit#oauth
api = Ossapi(client_id, client_secret)
# see docs for full list of endpoints
print(api.user("tybug").username)
print(api.user(12092800, mode="osu").username)
print(api.beatmap(221777).id)
ossapi provides an async variant, OssapiAsync
, which has an identical interface to Ossapi
:
import asyncio
from ossapi import OssapiAsync
api = OssapiAsync(client_id, client_secret)
async def main():
await api.user("tybug")
asyncio.run(main())
Read more about OssapiAsync on the docs.
You can use ossapi to interact with the api of other deployments of the osu website, such as https://dev.ppy.sh.
from ossapi import Ossapi
api = Ossapi(client_id, client_secret, domain="dev")
# get the dev server pp leaderboards
ranking = api.ranking("osu", "performance").ranking
# pearline06, as of 2023
print(ranking[0].user.username)
Read more about domains on the docs.
All endpoints for api v2.
- Beatmap Packs
- Beatmaps
- Beatmapsets
- Changelog
- Chat
- Comments
- Events
- Forums
- Friends
- Home
- Matches
- Me
- News
- OAuth
- Rankings
- Rooms
- Scores
- Seasonal Backgrounds
- Spotlights
- Users
- Wiki
You can get your api v1 key at https://osu.ppy.sh/home/account/edit#legacy-api.
Basic usage:
from ossapi import OssapiV1
api = OssapiV1("key")
print(api.get_beatmaps(user=53378)[0].submit_date)
print(api.get_match(69063884).games[0].game_id)
print(api.get_scores(221777)[0].username)
print(len(api.get_replay(beatmap_id=221777, user=6974470)))
print(api.get_user(12092800).playcount)
print(api.get_user_best(12092800)[0].pp)
print(api.get_user_recent(12092800)[0].beatmap_id)