Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Home

maxikg edited this page · 62 revisions
Clone this wiki locally

osu!api

https://osu.ppy.sh/api/

Api Version: 1.0

Overview

The osu! API is intended to allow the creation of third-party awesomeness. It is still in its infancy and primarily been written based on requests of users. If you have any additions you would like to see in the API, please file issues in this GitHub repository. Including a use case will help speed up implementation – if I see that it is going to be used for something cool I will be more likely to add it immediately.

Terms of Use

Use the API for good. Don't overdo it. If in doubt, ask before (ab)using :). this section may expand as necessary.

Current rate limit is set at an insanely high 1200 requests per minute, with burst capability of up to 200 beyond that. If you require more, you probably fall into the above category of abuse. If you are doing more than 60 requests a minute, you should probably give peppy a yell.

Requesting Access

You may request an API key from https://osu.ppy.sh/p/api.

Beatmap

/api/get_beatmaps

Overview

Retrieve general beatmap information.

URL
/api/get_beatmaps
Parameters
  • k - api key (required).
  • since - return all beatmaps ranked since this date. Must be a MySQL date.
  • s - specify a beatmapset_id to return metadata from.
  • b - specify a beatmap_id to return metadata from.
  • u - specify a user_id or a username to return metadata from.
  • type - specify if u is a user_id or a username. Use string for usernames or id for user_ids. Optional, default behaviour is automatic recognition (may be problematic for usernames made up of digits only).
  • m - mode (0 = osu!, 1 = Taiko, 2 = CtB, 3 = osu!mania). Optional, maps of all modes are returned by default.
  • a - specify whether converted beatmaps are included (0 = not included, 1 = included). Only has an effect is m is chosen and not 0. Converted maps show their converted difficulty rating. Optional, default is 0.
  • limit - amount of results.
Response

A JSON list containing all beatmaps (one per difficulty) matching criteria.

[{
    "approved"         : "1",                   // 3 = qualified, 2 = approved, 1 = ranked, 0 = pending, -1 = WIP, -2 = graveyard
    "approved_date"    : "2013-07-02 01:01:12", // date ranked, UTC+8 for now
    "last_update"      : "2013-07-06 16:51:22", // last update date, timezone same as above. May be after approved_date if map was unranked and reranked.
    "artist"           : "Luxion",
    "beatmap_id"       : "252002",              // beatmap_id is per difficulty
    "beatmapset_id"    : "93398",               // beatmapset_id groups difficulties into a set
    "bpm"              : "196",
    "creator"          : "RikiH_",
    "difficultyrating" : "5.59516",             // The amount of stars the map would have ingame and on the website
    "diff_size"        : "4",                   // Circle size value (CS)
    "diff_overall"     : "6",                   // Overall difficulty (OD)
    "diff_approach"    : "7",                   // Approach Rate (AR)
    "diff_drain"       : "6",                   // Healthdrain (HP)
    "hit_length"       : "113",                 // seconds from first note to last note not including breaks
    "source"           : "BMS",
    "title"            : "High-Priestess",      // song name
    "total_length"     : "145",                 // seconds from first note to last note including breaks
    "version"          : "Overkill",            // difficulty name
    "mode"             : "0"                    // game mode
}, { ... }, ...]

User

/api/get_user

Overview

Retrieve general user information.

URL
/api/get_user
Parameters
  • k - api key (required).
  • u - specify a user_id or a username to return metadata from (required).
  • m - mode (0 = osu!, 1 = Taiko, 2 = CtB, 3 = osu!mania). Optional, default value is 0.
  • type - specify if u is a user_id or a username. Use string for usernames or id for user_ids. Optional, default behaviour is automatic recognition (may be problematic for usernames made up of digits only).
  • event_days - Max number of days between now and last event date. Range of 1-31. Optional, default value is 1.
Response

A JSON list containing user information.

[{
    "user_id"      : "1",
    "username"     : "User name",
    "count300"     : "1337",      // Total amount for all ranked and approved beatmaps played
    "count100"     : "123",       // Total amount for all ranked and approved beatmaps played
    "count50"      : "69",        // Total amount for all ranked and approved beatmaps played
    "playcount"    : "42",        // Only counts ranked and approved beatmaps
    "ranked_score" : "666666",    // Counts the best individual score on each ranked and approved beatmaps
    "total_score"  : "999999998", // Counts every score on ranked and approved beatmaps
    "pp_rank"      : "2442",
    "level"        : "50.5050",
    "pp_raw"       : "3113",
    "accuracy"     : "98.1234",
    "count_rank_ss": "54",
    "count_rank_s" : "81",        // Counts for SS/S/A ranks on maps
    "count_rank_a" : "862",    
    "country"      : "DE",        // Uses the ISO3166-1 alpha-2 country code naming. See this for more information: http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2/wiki/ISO_3166-1_alpha-2)
    "events"       : [{           // Contains events for this user
        "display_html"  : "<img src='\/images\/A_small.png'\/>...",
        "beatmap_id"    : "222342",
        "beatmapset_id" : "54851",
        "date"      : "2013-07-07 22:34:04",
        "epicfactor"    : "1"      // How "epic" this event is (between 1 and 32)
    }, { ... }, ...]
}]

Scores

/api/get_scores

Overview

Retrieve information about the top 50 scores of a specified beatmap.

URL
/api/get_scores
Parameters
  • k - api key (required).
  • b - specify a beatmap_id to return score information from (required).
  • u - specify a user_id or a username to return score information for.
  • m - mode (0 = osu!, 1 = Taiko, 2 = CtB, 3 = osu!mania). Optional, default value is 0.
  • type - specify if u is a user_id or a username. Use string for usernames or id for user_ids. Optional, default behaviour is automatic recognition (may be problematic for usernames made up of digits only).
Response

A JSON list containing the top 50 scores of the specified beatmap.

[{
    "score"        : "1234567",
    "username"     : "User name",
    "count300"     : "300",
    "count100"     : "50",
    "count50"      : "10",
    "countmiss"    : "1",
    "maxcombo"     : "321",
    "countkatu"    : "10",
    "countgeki"    : "50",
    "perfect"      : "0",          // 1 = maximum combo of map reached, 0 otherwise
    "enabled_mods" : "76",         // bitwise flag representation of mods used. see reference
    "user_id"      : "1",
    "date"         : "2013-06-22 9:11:16",
    "rank"         : "SH",
    "pp"           : "1.3019"         //Float value , 4 decimals
}, { ... }, ...]

Best Performance

/api/get_user_best

Overview

Get the top scores for the specified user.

URL
/api/get_user_best
Parameters
  • k - api key (required).
  • u - specify a user_id or a username to return best scores from (required).
  • m - mode (0 = osu!, 1 = Taiko, 2 = CtB, 3 = osu!mania). Optional, default value is 0.
  • limit - amount of results (range between 1 and 50 - defaults to 10).
  • type - specify if u is a user_id or a username. Use string for usernames or id for user_ids. Optional, default behavior is automatic recognition (may be problematic for usernames made up of digits only).
Response

A JSON list containing the top 10 scores for the specified user.

[{
    "beatmap_id"   : "222342",
    "score"        : "1234567",
    "username"     : "User name",
    "maxcombo"     : "321",
    "count300"     : "300",
    "count100"     : "50",
    "count50"      : "10",
    "countmiss"    : "1",
    "countkatu"    : "10",
    "countgeki"    : "50",
    "perfect"      : "0",          // 1 = maximum combo of map reached, 0 otherwise
    "enabled_mods" : "76",         // bitwise flag representation of mods used. see reference
    "user_id"      : "1",
    "date"         : "2013-06-22 9:11:16",
    "rank"         : "SH",
    "pp"           : "1.3019"         //Float value , 4 decimals
}, { ... }, ...]

Recently Played

/api/get_user_recent

Overview

Gets the user's ten most recent plays.

URL
/api/get_user_recent
Parameters
  • k - api key (required).
  • u - specify a user_id or a username to return recent plays from (required).
  • m - mode (0 = osu!, 1 = Taiko, 2 = CtB, 3 = osu!mania). Optional, default value is 0.
  • limit - amount of results (range between 1 and 50 - defaults to 10).
  • type - specify if u is a user_id or a username. Use string for usernames or id for user_ids. Optional, default behavior is automatic recognition (may be problematic for usernames made up of digits only).
Response

A JSON list containing the user's ten most recent songs played.

[{
    "beatmap_id"   : "987654",
    "score"        : "1234567",
    "maxcombo"     : "321",
    "count50"      : "10",
    "count100"     : "50",
    "count300"     : "300",
    "countmiss"    : "1",
    "countkatu"    : "10",
    "countgeki"    : "50",
    "perfect"      : "0",          // 1 = maximum combo of map reached, 0 otherwise
    "enabled_mods" : "76",         // bitwise flag representation of mods used. see reference
    "user_id"      : "1",
    "date"         : "2013-06-22 9:11:16",
    "rank"         : "SH"
}, { ... }, ...]

Multiplayer

/api/get_match

Overview

Retrieve information about multiplayer match.

URL
/api/get_match
Parameters
  • k - api key (required).
  • mp - match id to get information from (required).
Response

A JSON list containing match information, and player's result.

[{
    "match":{
        "match_id"     : "1936471",
        "name"         : "Marcin's game",
        "start_time"   : "2013-10-06 03:34:54",
        "end_time"     : null             // not supported yet - always null
    },
    "games":[{
        "game_id"      : "45668898",
        "start_time"   : "2013-10-06 03:36:27",
        "end_time"     : "2013-10-06 03:40:01",
        "beatmap_id"   : "181717",
        "play_mode"    : "0",              // standard = 0, taiko = 1, ctb = 2, o!m = 3
        "match_type"   : "0",              // couldnt find
        "scoring_type" : "0",              // winning condition: score = 0, accuracy = 1, combo = 2
        "team_type"    : "0",              // Head to head = 0, Tag Co-op = 1, Team vs = 2, Tag Team vs = 3
        "mods"         : "0",              // global mods, see reference below
        "scores"       : [{
            "slot"          : "0",         // 0 based index of player's slot
            "team"          : "0",         // if mode doesn't support teams it is 0, otherwise 1 = blue, 2 = red
            "user_id"       : "722665",
            "score"         : "3415874",
            "maxcombo"      : "411",
            "rank"          : "0",         // not used
            "count50"       : "0",
            "count100"      : "11",
            "count300"      : "425",
            "countmiss"     : "1",
            "countgeki"     : "67",
            "countkatu"     : "9",
            "perfect"       : "0",        // full combo
            "pass"          : "1"         // if player failed once it is 0, otherwise 1
        },{ ... }  ...]
    }, { ... },  ...]
}]

Reference

Mods

Bitwise enum representing a combination of enabled mods.

enum Mods
{
    None           = 0,
    NoFail         = 1,
    Easy           = 2,
    //NoVideo      = 4,
    Hidden         = 8,
    HardRock       = 16,
    SuddenDeath    = 32,
    DoubleTime     = 64,
    Relax          = 128,
    HalfTime       = 256,
    Nightcore      = 512, // Only set along with DoubleTime. i.e: NC only gives 576
    Flashlight     = 1024,
    Autoplay       = 2048,
    SpunOut        = 4096,
    Relax2         = 8192,  // Autopilot?
    Perfect        = 16384,
    Key4           = 32768,
    Key5           = 65536,
    Key6           = 131072,
    Key7           = 262144,
    Key8           = 524288,
    keyMod         = Key4 | Key5 | Key6 | Key7 | Key8,
    FadeIn         = 1048576,
    Random         = 2097152,
    LastMod        = 4194304,
    FreeModAllowed = NoFail | Easy | Hidden | HardRock | SuddenDeath | Flashlight | FadeIn | Relax | Relax2 | SpunOut | keyMod,
    Key9           = 16777216,
    Key10          = 33554432,
    Key1           = 67108864,
    Key3           = 134217728,
    Key2           = 268435456
}
Something went wrong with that request. Please try again.