Skip to main content

The definitive python wrapper for the osu! api

Project description

ossapi (documentation) PyPI version

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

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.

Other domains

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.

Endpoints

All endpoints for api v2.

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)

Project details


Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ossapi-5.2.1.tar.gz (122.8 kB view details)

Uploaded Source

Built Distribution

ossapi-5.2.1-py3-none-any.whl (94.6 kB view details)

Uploaded Python 3

File details

Details for the file ossapi-5.2.1.tar.gz.

File metadata

  • Download URL: ossapi-5.2.1.tar.gz
  • Upload date:
  • Size: 122.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.12.10

File hashes

Hashes for ossapi-5.2.1.tar.gz
Algorithm Hash digest
SHA256 a323fb6714e346cceee55edd8b24f9c8443837c09d35b006a6253ca8fbe0eb5d
MD5 09d53d445c08e1a87dc10de2a1e9afc8
BLAKE2b-256 99ef76b92f01e2c273b228195e121f34b7ee3493099a6bca2824167b32825be4

See more details on using hashes here.

File details

Details for the file ossapi-5.2.1-py3-none-any.whl.

File metadata

  • Download URL: ossapi-5.2.1-py3-none-any.whl
  • Upload date:
  • Size: 94.6 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.12.10

File hashes

Hashes for ossapi-5.2.1-py3-none-any.whl
Algorithm Hash digest
SHA256 f2eb33977fb8834ab2af8d88d63fe69b19c534f4653723659a686bea5aeadefb
MD5 bfd4af87f3e842c63d4da3e273b0bf69
BLAKE2b-256 ecbe0b613f4df60fd901673fa7714ad02c77a3acac59edd4781c7a9cac3f962a

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page