Creating a Client

Before we can use ossapi, we’ll need to create an OAuth client.

Navigate to your settings page and click “New OAuth Application”. You can name it anything you like, but choose a callback url on localhost. For example, http://localhost:3914/. Any port greater than 1024 is fine as long as you don’t choose something another application is using.

When you create the application, it will show you a client id and secret. Take note of these two values.

With this information in hand, we’re ready to create an Ossapi instance:

from ossapi import Ossapi

client_id = None
client_secret = None
api = Ossapi(client_id, client_secret)

Using api

Let’s make a few simple api calls to make sure things are working:

from ossapi import Ossapi, UserLookupKey, GameMode, RankingType

client_id = None
client_secret = None
api = Ossapi(client_id, client_secret)

user = api.user("tybug", key=UserLookupKey.USERNAME)
print(user.id)

top50 = api.ranking(GameMode.OSU, RankingType.PERFORMANCE)
# can also use string version of enums
top50 = api.ranking("osu", "performance")

print(top50.ranking[0].user.username) # mrekk as of 2022

With that, you’re ready to go! Take a look at Endpoints to see documentation for all endpoints, grouped by category (or look at the left sidebar).

ossapi’s documentation follows the style of osu-web’s documentation very closely, and models in ossapi match osu-web almost 1:1, so you can use the docs of one to supplement the other.

Note

There are rare exceptions where ossapi’s models have different attribute names from osu-web. For example, ChangelogSearch.from_ is returned as from in the api, which is a keyword in python.

You can also continue reading about scopes and grants in Grants.