[][src]Crate rosu

rosu is a rust wrapper for osu!.

The wrapper provides access to the osu!api's beatmap, user, score, user-best, user-recent, and match endpoints. Note: Only v1 of the osu!api is supported.

An API key can be generated here.

Simply initialize an Osu client with the api key, call any of its get_* methods and await its result.


use chrono::{offset::TimeZone, DateTime, Utc};
use rosu::{
    Osu, OsuResult,

async fn main() -> OsuResult<()> {
    // Initialize the client
    let osu = Osu::new("osu_api_key");
    // If `cache` feature enabled:
    // let osu = Osu::new("osu_api_key", redis_pool, rosu::OsuCached::User);

    // --- Retrieving top scores ---

    // Accumulate all important arguments for the request
    let request = osu.top_scores("Badewanne3")
    // Await the request
    let mut scores: Vec<Score> = request.await?;
    match scores.pop() {
        Some(score) => {
            // Retrieve user of the score
            let user = score.get_user(&osu).mode(GameMode::STD).await?;
            // ...
        None => println!("No top scores found"),

    // --- Retrieving beatmaps ---

    let since_date: DateTime<Utc> = Utc
        .datetime_from_str("2018-11-13 23:01:28", "%Y-%m-%d %H:%M:%S")
    let request = osu.beatmaps()
    let mut maps: Vec<Beatmap> = request.await?;
    if let Some(map) = maps.pop() {
        let leaderboard: Vec<Score> = map.get_global_leaderboard(&osu).limit(13).await?;
        // ...

    // --- Retrieving user ---

    let user: Option<User> = osu.user("Badewanne3").await?;
    // ...

    // --- Retrieving match ---

    let osu_match: Match = osu.osu_match(58494587).await?;
    // ...



serializeProvides serialization for all structs in the models dirserde-repr
metricsMake the client count each request type and enable a method on the client to get a prometheus::IntCounterVecprometheus
cacheCache API results through a redis connection for a given durationdarkredis, serialize

Error handling

OsuErrors are nested through their source errors. To read them, one can use a small unwind macro such as:

macro_rules! unwind_error {
    ($log:ident, $err:ident, $($arg:tt)+) => {
            $log!($($arg)+, $err);
            let mut err: &dyn ::std::error::Error = &$err;
            while let Some(source) = err.source() {
                $log!("  - caused by: {}", source);
                err = source;

use rosu::{Osu, OsuResult, model::GameMode};

async fn main() {
    let osu = Osu::new("osu_api_key");
    let mode = GameMode::STD;
    if let Err(why) = osu.user("badewanne3").mode(mode).await {
        unwind_error!(println, why, "Error while retrieving user for mode {}", mode);



Contains structs that are parsed from the osu!api


Re-exporting a bunch of things


Contains the Future structs that request the data



The main osu client. Cheap to clone.


A builder for the main Osu client.



Main error enum

Type Definitions


Result<_, OsuError>