v5.1.1

• make mode parameter of api.scores optional
• add proper model for Score.maximum_statistics

v5.1.0

• add new api.scores endpoint
• fix some OssapiAsync methods not actually being async
• add many attributes to MultiplayerScore
• fix MultiplayerScore.rank type
• mark BeatmapsetEvent.comment as optional
• mark BeatmapsetEventType.DISQUALIFY and BeatmapsetEventType.NOMINATION_RESET as accepting str
• mark BeatmapsetDiscussion.last_post_at as optional
• mark Room.ends_at as optional

v5.0.4

• add Beatmap.owners

v5.0.3

• add BeatmapsetEventCommentOwnerChange.new_users
• hotfix for api.beatmapset_events types in v5.0.2

v5.0.2

• change Score.ended_at: Optional[Datetime] to Score.ended_at: Datetime; I don't believe it can be None.
• add NewsPost.first_image_2x
• fix BeatmapsetEventCommentNoPost and BeatmapsetEventCommentNone types (fixes api.beatmapset_events erroring in some cases)

v5.0.1

• fix api_version header not being passed in OssapiAsync

v5.0.0

This release implements the x-api-version header of the osu api. It adds a new parameter api_version to Ossapi, which allows you to specify which version of the api your code supports. The attributes in the returned models may be different for certain endpoints depending on the passed api_version. For instance, by setting api_version=20220705 or higher, endpoints will start returning the new score format. This contains lazer-specific information such as settings for mods, correct accuracy for lazer scores, etc.

This is a major release bump for ossapi because I have set api_version to default to 20241024 (the current date as of time of release). This means that if your code relied on the previous structure score structure, it may break. It also means that by upgrading you will start using the newest structures by default. If you want to upgrade but want to continue using the old model structure, pass api_version=0 (or some sufficiently small version like api_version=20200101 is very likely to also work). You can change to the new structure at any time by setting a higher api_version.

I recommend that you hardcod a version string regardless, to be explicit about which api version you are using. You can choose the current date if you are happy with the current models you are receiving from the api.

Changes

• add api_version parameter to Ossapi
• add new Ossapi.users_lookup endpoint
• add beatmapset_id parameter to api.beatmapet_events endpoint
• add Nominations.eligible_main_rulesets
• add UserStatistics.rank_change_since_30_days
• add RoomCategory.DAILY_CHALLENGE
• add User.{profile_hue, daily_challenge_stats}
• add BeatmapsetEventCommentWithNominators.beatmap_ids
• change Nominations.required to Nominations.required_meta
• mark Rankings.total as optional
• mark UserStatistics.{play_time, pp} as optional

v5.0.0b1

This release implements the x-api-version header of the osu api. It adds a new parameter api_version to Ossapi, which allows you to specify which version of the api your code supports. The attributes in the returned models may be different for certain endpoints depending on the passed api_version. For instance, by setting api_version=20220705 or higher, endpoints will start returning the new score format. This contains lazer-specific information such as settings for mods, correct accuracy for lazer scores, etc.

This is a major release bump for ossapi because I have set api_version to default to 20241024 (the current date as of time of release). This means that if your code relied on the previous structure score structure, it may break. It also means that by upgrading you will start using the newest structures by default. If you want to upgrade but want to continue using the old model structure, pass api_version=0 (or some sufficiently small version like api_version=20200101 is very likely to also work). You can opt-in to the new structure at any time by setting a higher api version.

I recommend that you hardcod a version string regardless, to be explicit about which api version you are using. You can choose the current date if you are happy with the current models you are receiving from the api.

Changes

• add api_version parameter to Ossapi
• add new Ossapi.users_lookup endpoint
• add beatmapset_id parameter to api.beatmapet_events endpoint
• add Nominations.eligible_main_rulesets
• add UserStatistics.rank_change_since_30_days
• add RoomCategory.DAILY_CHALLENGE
• add User.{profile_hue, daily_challenge_stats}
• add BeatmapsetEventCommentWithNominators.beatmap_ids
• change Nominations.required to Nominations.required_meta
• mark Rankings.total as optional
• mark UserStatistics.{play_time, pp} as optional

v4.0.0

The big change in this release is to account for the migration from old score ids (https://osu.ppy.sh/scores/osu/3772000814) to new score ids (https://osu.ppy.sh/scores/1312718771). The former requires the gamemode while the latter does not. Endpoints which previously took both a gamemode and a score id have been changed to take just a score id (new format), while the previous endpoint behavior was kept under a different method name.

Breaking changes

• rename api.score to api.score_mode
• add a new api.score method which takes the new score id format
• rename api.download_score to api.download_score_mode
• rename BeatmapScores.userScore to BeatmapScores.user_score
• add a new api.download_score method which takes the new score id format
• rename before and after parameters of api.match to before_id and after_id, to better reflect that the api filters by id and not something like time
• remove Domain.LAZER
  • lazer.ppy.sh was decommissioned in the past few months, so this parameter has no effect and in fact causes errors. Lazer data is now live on the main site and you do not need to pass a Domain to access it

Migration guide

• change any api.score calls to api.score_mode (and consider migrating to the new api.score, to use the new score ids without gamemodes)
• change any api.download_score calls to api.download_score_mode (and consider migrating to the new api.download_score, for the same reason)
• rename any api.match(before=..., after=...) calls to api.match(before_id=..., after_id=...)

Non-breaking changes

• add legacy_only parameter to applicable endpoints
• make Statistics counts optional
• correctly type cursor_string as optional

v4.0.0beta1

This is a beta release. You can install it with pip install -U --pre ossapi. I may make breaking changes based on feedback before releasing 4.0.0 final (though I don't expect to).

The big change in this release is to account for the migration from old score ids (https://osu.ppy.sh/scores/osu/3772000814) to new score ids (https://osu.ppy.sh/scores/1312718771). The former requires the gamemode while the latter does not. Endpoints which previously took both a gamemode and a score id have been changed to take just a score id (new format), while the previous endpoint behavior was kept under a different method name.

Breaking changes

• rename api.score to api.score_mode
• add a new api.score method which takes the new score id format
• rename api.download_score to api.download_score_mode
• add a new api.download_score method which takes the new score id format
• rename before and after parameters of api.match to before_id and after_id, to better reflect that the api filters by id and not something like time
• remove Domain.LAZER
  • lazer.ppy.sh was decommissioned in the past few months, so this parameter has no effect and in fact causes errors. Lazer data is now live on the main site and you do not need to pass a Domain to access it

Migration guide

• change any api.score calls to api.score_mode (and consider migrating to the new api.score, to use the new score ids without gamemodes)
• change any api.download_score calls to api.download_score_mode (and consider migrating to the new api.download_score, for the same reason)
• rename any api.match(before=..., after=...) calls to api.match(before_id=..., after_id=...)

Non-breaking changes

• make Statistics counts optional
• correctly type cursor_string as optional