osu!droid Public API Documentation

droid-api-docs.md

This document serves as a documentation for the "public" osu!droid API. It is minimalistic, but all information provided is correct as of osu!droid version 1.8.3.

Base URL

https://osudroid.moe/api

All requests must specify an API key via the apiKey parameter unless specified otherwise.

In endpoints where an API key is required:

• If the parameter is omitted, a raw FAILED 1 response with a 400 HTTP status code will be returned.
• If the API key is not registered or does not have permission, a raw FAILED -1 response with a 403 HTTP status code will be returned.

Endpoints

GET /getuserinfo.php

Retrieves the information of a player and their 50 most recent scores.

Parameters

Either uid or username must be specified. If both parameters are specified, uid will be used.

Name	Accepted Types	Default	Description
uid	integer (≥2417)	N/A	The user ID of the player
username	string (2-20 characters)	N/A	The username of the player

Examples

• /getuserinfo.php?uid=51076

  Retrieves the information of the player with the user ID 51076.

• /getuserinfo.php?username=Rian8337

  Retrieves the information of the player with the username Rian8337.

Responses

If a player is not found, an empty JSON ({}) will be returned with a 404 HTTP status code.

If a player is found, the following JSON will be returned:

{
    "id": 51076, // User ID of the player
    "username": "Rian8337", // Username of the player
    "score": 20716857314, // Total score of the player
    "playcount": 775, // Play count of the player
    "accuracy": 0.983, // Overall accuracy of the player
    "region": "ID", // Region of the player in ISO 3166-1 alpha-2 format
    "rank": 116, // Global rank of the player
    "pp": 8475.14, // Performance points of the player
    "recent": [
        // List of recent scores, up to 50 scores
        {
            "id": 6398727, // ID of score
            "score": 57098652, // Achieved total score
            "filename": "yaseta - Bluenation (Meg) [Grace]", // Name of beatmap
            "combo": 2149, // Achieved maximum combo
            "mark": "S", // Achieved rank, see `Mark` section
            "mode": "s|", // Mods used in the score, see `Mods` section
            "accuracy": 0.9515, // Achieved accuracy, from 0 to 1
            "perfect": 1581, // Amount of 300s
            "good": 119, // Amount of 100s
            "bad": 4, // Amount of 50s
            "miss": 0, // Amount of misses
            "date": 1737468073, // Epoch time of score submission in seconds
            "hash": "257099a7bc15792928a55c1a8510e934", // MD5 hash of beatmap
            "pp": 255.356, // Performance points achieved, or `null` if there is no performance points achieved. Always `null` in beatmaps that are not ranked or approved.
        },
        // ...
    ],
}

GET /scoresearchv2.php

Retrieves scores from a player or beatmap.

Parameters

Either uid, username, or hash must be specified. If both uid and username are specified, uid will be used.

The hash and page parameters can be combined with the uid or username parameter.

Name	Accepted Types	Default	Description
uid	integer (≥2417)	N/A	The user ID of the player
username	string (2-20 characters)	N/A	The username of the player
hash	string (32 characters)	N/A	The MD5 hash of the beatmap
order	sid, date, score, pp	sid	The order of which to return scores, as follows: sid: Score ID, ascending date: Submission date, descending score: Achieved total score, descending pp: Achieved performance points, descending
page	integer (≥0)	0	The zero-based page to retrieve scores at. Each page contains at most 100 scores

Examples

• /scoresearchv2.php?uid=51076&order=pp

  Retrieves scores from the player with the user ID 51076 and sorts them by achieved performance points descendingly.

• /scoresearchv2.php?username=Rian8337&order=date

  Retrieves scores from the player with the username Rian8337 and sorts them by submission date descendingly.

• /scoresearchv2.php?hash=8f91aa532b943ceaf29a5d761366130d&order=pp

  Retrieves scores from the beatmap with the given MD5 hash and sorts them by achieved performance points descendingly.

• /scoresearchv2.php?hash=8f91aa532b943ceaf29a5d761366130d&order=pp&page=1

  Retrieves scores from the beatmap with the given MD5 hash, sorts them by achieved performance points descendingly, and returns the second page.

• /scoresearchv2.php?uid=51076&hash=8f91aa532b943ceaf29a5d761366130d

  Retrieves scores from the player with the user ID 51076 that was set on the beatmap with the given MD5 hash.

Responses

If the provided page is not an integer, a raw FAILED INVALID_PAGE response with a 400 HTTP status code will be returned.

If the provided MD5 hash is not 32 characters in length, a raw FAILED INVALID_HASH response with a 400 HTTP status code will be returned.

If the provided order parameter is invalid, a raw FAILED UNKNOWN_ORDER response with a 400 HTTP status code will be returned.

If no uid, username, or hash parameter is given, a raw FAILED NOT_SUPPORTED_TYPE response with a 400 HTTP status code will be returned.

In other scenarios, the following JSON is returned:

[
    // List of scores, up to 100 scores
    {
        "id": 6398727, // ID of score
        "uid": 51076, // User ID of the player
        "username": "Rian8337", // Username of the player
        "filename": "yaseta - Bluenation (Meg) [Grace]", // Name of beatmap
        "score": 57098652, // Achieved total score
        "combo": 2149, // Achieved maximum combo
        "mark": "S", // Achieved rank, see `Mark` section
        "mode": "s|", // Mods used in the score, see `Mods` section
        "accuracy": 0.9515, // Achieved accuracy, from 0 to 1
        "perfect": 1581, // Amount of 300s
        "good": 119, // Amount of 100s
        "bad": 4, // Amount of 50s
        "miss": 0, // Amount of misses
        "date": 1737468073, // Epoch time of score submission in seconds
        "hash": "257099a7bc15792928a55c1a8510e934", // MD5 hash of beatmap
        "pp": 255.356, // Performance points achieved, or `null` if there is no performance points achieved. Always `null` in beatmaps that are not ranked or approved.
    },
    // ...
]

GET /upload/{score ID}.odr

Retrieves the replay file of a score from its score ID. The retrieved score will be the best score in terms of total score.

This endpoint does not require an API key.

GET /bestpp/{score ID}.odr

Retrieves the replay file of a score from its score ID. The retrieved score will be the best score in terms of performance points.

This endpoint does not require an API key.

Data Structures

Mods

Mods are represented by a character, with additional information for other settings after the first pipe character (|). In some scores, this pipe character may not be present.

When No Mod is used, only the pipe character or empty string will be present.

Each character represents the following mod:

Character	Mod	Abbreviation	Ranked
a	Auto	AT	❌
b	Traceable	TC	❌
c	Night Core	NC	✅
d	Double Time	DT	✅
e	Easy	EZ	✅
f	Perfect	PF	✅
h	Hidden	HD	✅
i	Flashlight	FL	✅
l	Really Easy	RE	❌
n	No Fail	NF	✅
p	Autopilot	AP	❌
r	Hard Rock	HR	✅
s	Precise	PR	✅
t	Half Time	HT	✅
u	Sudden Death	SD	✅
v	ScoreV2	V2	❌
x	Relax	RX	❌

Additional information after the first pipe character can be interpreted as follows (all of them are not always present):

Section	Description
x<float>	Custom speed multiplier (multiplies on top of rate adjusting mods)
CS<float>	Forced circle size
AR<float>	Forced approach circle
OD<float>	Forced overall difficulty
HP<float>	Forced health drain rate
FLD<float>	Flashlight area follow delay, in seconds. Only present if the Flashlight mod is used and the default follow delay (0.12 seconds) is not used

Examples

• (empty string) means No Mod is used
• | means No Mod is used
• rd means Hard Rock and Double Time mods are used
• s| means the Precise mod is used
• rh|1.15x means:
  • The mods are Hard Rock and Hidden
  • The custom speed multiplier is 1.15
• rhdf|1.35x|CS4.2|AR10.0|OD9.8|HP4.6|FLD0.6 means:
  • The mods are Hard Rock, Hidden, Double Time, and Flashlight
  • The custom speed multiplier is 1.35
  • The forced circle size is 4.2
  • The forced approach rate is 10
  • The forced overall difficulty is 9.8
  • The forced health drain rate is 4.6
  • The Flashlight area follow delay is 0.6 seconds

Mark

A mark represents the rank of a score, denoted by one of the following:

• XH (silver SS)
• X (SS)
• SH (silver S)
• S
• A
• B
• C
• D