ossapi 3.4.4

Complete python wrapper for osu! api v2 and v1.

ossapi (documentation)

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.

• Installation
• Quickstart
• Async
• Lazer
• Endpoints
  • Beatmap Packs
  • Beatmaps
  • Beatmapsets
  • Changelog
  • Chat
  • Comments
  • Events
  • Forums
  • Friends
  • Home
  • Matches
  • Me
  • News
  • OAuth
  • Rankings
  • Rooms
  • Scores
  • Seasonal Backgrounds
  • Spotlights
  • Users
  • Wiki
• API v1 Usage

Installation

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/.

Quickstart

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)

Async

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.

Lazer

You can retrieve lazer-specific data (scores, leaderboards, etc) with ossapi:

from ossapi import Ossapi

api_lazer = Ossapi(client_id, client_secret, domain="lazer")

# best score on the lazer server (lazer + osu scores combined)
scores = api_lazer.user_scores(12092800, "best")
print(scores[0].pp)

Read more about domains on the docs.

Endpoints

All endpoints for api v2.

• Beatmap Packs
  • api.beatmap_pack
  • api.beatmap_packs
• Beatmaps
  • api.beatmap
  • api.beatmap_attributes
  • api.beatmap_scores
  • api.beatmap_user_score
  • api.beatmap_user_scores
  • api.beatmaps
• Beatmapsets
  • api.beatmapset
  • api.beatmapset_discussion_posts
  • api.beatmapset_discussion_votes
  • api.beatmapset_discussions
  • api.beatmapset_events
  • api.search_beatmapsets
• Changelog
  • api.changelog_build
  • api.changelog_build_lookup
  • api.changelog_listing
• Chat
  • api.send_announcement
  • api.send_pm
• Comments
  • api.comment
  • api.comments
• Events
  • api.events
• Forums
  • api.forum_create_topic
  • api.forum_edit_post
  • api.forum_edit_topic
  • api.forum_reply
  • api.forum_topic
• Friends
  • api.friends
• Home
  • api.search
• Matches
  • api.match
  • api.matches
• Me
  • api.get_me
• News
  • api.news_listing
  • api.news_post
• OAuth
  • api.revoke_token
• Rankings
  • api.ranking
• Rooms
  • api.multiplayer_scores
  • api.room
  • api.room_leaderboard
  • api.rooms
• Scores
  • api.download_score
  • api.score
• Seasonal Backgrounds
  • api.seasonal_backgrounds
• Spotlights
  • api.spotlights
• Users
  • api.user
  • api.user_beatmaps
  • api.user_kudosu
  • api.user_recent_activity
  • api.user_scores
  • api.users
• Wiki
  • api.wiki_page

API v1 Usage

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)