Permalink
Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
1218 lines (1065 sloc) 36.4 KB
name
Ripple API (v1)

Ripple API

The Ripple API is an API built and designed specifically for Ripple. The base URL is:

https://ripple.moe/api/v1

E.g., the URL for a GET /ping request would be

https://ripple.moe/api/v1/ping

General indications specified by the Appendix apply here.

Table of Contents

Miscellaneous

GET /ping

Check the API is alive, and check your token's privileges.

Response

Field name Type Value
message string A human-readable message, notifying you about a token not given or telling you a message taken straight from surprise_me.
privileges uint64 Privileges of the token.
privileges_string string A string representation of privieges, for easily understanding the token's privileges.
user_id int The token's user ID.
user_privileges uint64 A bitwise enum containing the privileges of the user (not the token!).
user_privileges_string string A string representation of the privileges of user_privileges.

Examples

$ http 'https://ripple.moe/api/v1/ping'
HTTP/1.1 200 OK
CF-RAY: 2f76f6d2f0990e2a-MXP
Connection: keep-alive
Content-Encoding: gzip
Content-Length: 208
Content-Type: application/json; charset=utf-8
Date: Tue, 25 Oct 2016 16:14:53 GMT
Server: cloudflare-nginx
Vary: Accept-Encoding

{
    "code": 200,
    "message": "You have not given us a token, so we don't know who you are! But you can still login with POST /tokens ヽ( ★ω★)ノ",
    "privileges": 0,
    "privileges_string": "",
    "user_id": 0,
    "user_privileges": 0,
    "user_privileges_string": ""
}
$ http 'https://ripple.moe/api/v1/ping' X-Ripple-Token:<strip>
HTTP/1.1 200 OK
CF-RAY: 2f76fb0ef4a63d7d-MXP
Connection: keep-alive
Content-Encoding: gzip
Content-Length: 302
Content-Type: application/json; charset=utf-8
Date: Tue, 25 Oct 2016 16:17:47 GMT
Server: cloudflare-nginx
Vary: Accept-Encoding

{
    "code": 200,
    "message": "The brace is on fire! \(=^‥^)/’`",
    "privileges": 1048576,
    "privileges_string": "",
    "user_id": 1009,
    "user_privileges": 3141499,
    "user_privileges_string": "UserPublic, UserNormal, AdminAccessRAP, AdminManageUsers, AdminBanUsers, AdminSilenceUsers, AdminManageBeatmap, AdminManageServer, AdminManageSetting, AdminManageBetaKey, AdminManageDocs, AdminManageBadges, AdminViewRAPLogs, AdminManagePrivilege, AdminSendAlerts, AdminChatMod, AdminKickUsers, UserTournamentStaff"
}

GET /surprise_me

A test API endpoint that spits some random sentences.

Response

Field name Type Value
cats []string Random sentences and cats and things.

Examples

$ http 'https://ripple.moe/api/v1/surprise_me'
HTTP/1.1 200 OK
CF-RAY: 2f77065604df0e18-MXP
Connection: keep-alive
Content-Encoding: gzip
Content-Length: 1155
Content-Type: application/json; charset=utf-8
Date: Tue, 25 Oct 2016 16:25:29 GMT
Server: cloudflare-nginx
Vary: Accept-Encoding

{
    "cats": [
        "Hi! I'm Flowey! Flowey the flower! o(^・x・^)o",
        "sudo rm -rf / (=`ェ´=)",
        "PP when? Σ(*ノ´>ω<。`)ノ",
        "Ripple devs are actually cats d(=^・ω・^=)b",
        "Ripple devs are actually cats ((≡^⚲͜^≡))",
        "Hi! I'm Flowey! Flowey the flower! (ノ。≧◇≦)ノ",
        "deverupa ga daisuki! (=TェT=)",
        "PP when? Σ(*ノ´>ω<。`)ノ",
        "sudo rm -rf / d(=^・ω・^=)b",
		...
    ],
    "code": 200
}

Tokens

GET /tokens

Allows to retrieve information about the API tokens of the current user. It will not return the tokens themselves (as their value is not stored, only their MD5 hash). Implements pagination.

Response (tokens)

Field name Type Value
description string Description of the token, see POST /tokens
privileges uint64 The privileges of that token, as specified in Privileges

Examples

$ http 'https://ripple.moe/api/v1/tokens' X-Ripple-Token:<strip>
HTTP/1.1 200 OK
CF-RAY: 2f8efafccf1f432e-MXP
Connection: keep-alive
Content-Encoding: gzip
Content-Length: 145
Content-Type: application/json; charset=utf-8
Date: Fri, 28 Oct 2016 14:12:02 GMT
Server: cloudflare-nginx
Vary: Accept-Encoding

{
    "code": 200,
    "tokens": [
        {
            "description": "",
            "id": 1,
            "privileges": 1048576
        },
        {
            "description": "",
            "id": 3,
            "privileges": 1048575
        },
        {
            "description": "",
            "id": 4,
            "privileges": 1048576
        },
        {
            "description": "",
            "id": 63,
            "privileges": 1048576
        },
        {
            "description": "",
            "id": 28433,
            "privileges": 1048576
        },
        {
            "description": "",
            "id": 80095,
            "privileges": 0
        }
    ]
}

GET /tokens/self

Retrieves information about the passed token. Explanation on the returned fields.

Examples

$ http 'https://ripple.moe/api/v1/tokens/self' X-Ripple-Token:<strip>
HTTP/1.1 200 OK
CF-RAY: 2f8f08531b114316-MXP
Connection: keep-alive
Content-Encoding: gzip
Content-Length: 85
Content-Type: application/json; charset=utf-8
Date: Fri, 28 Oct 2016 14:21:09 GMT
Server: cloudflare-nginx
Vary: Accept-Encoding

{
    "code": 200,
    "description": "",
    "id": 4,
    "privileges": 1048576
}

GET /tokens/self/delete

Deletes the current token.

Errors

Code Meaning
400 No (valid) token was given.

Examples

$ http 'https://ripple.moe/api/v1/tokens/self/delete' X-Ripple-Token:<strip>
HTTP/1.1 200 OK
CF-RAY: 2f8f0adcdbed432e-MXP
Connection: keep-alive
Content-Encoding: gzip
Content-Length: 57
Content-Type: application/json; charset=utf-8
Date: Fri, 28 Oct 2016 14:22:53 GMT
Server: cloudflare-nginx
Vary: Accept-Encoding

{
    "code": 200,
    "message": "Bye!"
}
$ http 'https://ripple.moe/api/v1/tokens/self/delete' X-Ripple-Token:someimpossibletoken
HTTP/1.1 400 Bad Request
CF-RAY: 2f8f0aec9d6b0e48-MXP
Connection: keep-alive
Content-Encoding: gzip
Content-Length: 113
Content-Type: application/json; charset=utf-8
Date: Fri, 28 Oct 2016 14:22:55 GMT
Server: cloudflare-nginx
Vary: Accept-Encoding

{
    "code": 400,
    "message": "How should we delete your token if you haven't even given us one?!"
}

Users

GET /users

Retrieves information about one or more users. Implements pagination (except if you pass name or id).

If you're looking to build a library, you should never pass id or name - those are kepts only for backwards compatibility, and if you don't want to get an headache you're better off passing iid or nname, they are uniform and coherent with all the other results returned by this endpoint, with an exception for those passed by id or name, of course.

Parameters

If any of these are passed, they will always returns only ONE user:

Name Description Required?
id The ID of the user to return. No
name The username of the user to return. No

Always returns users in an array called users:

Name Description Required?
iid The ID of the user to return. No
nname The username of the user to return. No
privileges Privileges of the user must be EXACTLY the ones passed. No
has_privileges The user must have at least all of the privileges given, however it could have more than those passed (bitwise AND) No
has_not_privileges The user must not have any of these privileges. No
country User must be of a specific country. No
name_aka User must have the passed username_aka. No
privilege_group Name of the privilege group the user must belong to. No

IN Parameters

Name Description
ids User IDs from where to choose from.
names Usernames from where to choose from.
names_aka Alternative usernames from where to choose from.
countries Countries from where to choose from.

Sorting

Field Description
id ...
username ...
privileges ...
donor_expire Day in which the donor will expire, can be used to get donors in order of those who donated the most
latest_activity datetime the user was last active on Ripple.
silence_end Datetime the silence ended.

Response

If either id or name is passed, then the result will be embedded in the global response object. If neither of those two are passed, the users returned will be in the array users. Of course, the user(s) to be returned will be of type User.

Examples

$ http 'https://ripple.moe/api/v1/users?id=1009' X-Ripple-Token:<strip>
HTTP/1.1 200 OK
CF-RAY: 2f9148a43b883dd1-MXP
Connection: keep-alive
Content-Encoding: gzip
Content-Length: 174
Content-Type: application/json; charset=utf-8
Date: Fri, 28 Oct 2016 20:54:34 GMT
Server: cloudflare-nginx
Vary: Accept-Encoding

{
    "code": 200,
    "country": "IT",
    "id": 1009,
    "latest_activity": "2016-10-25T20:25:58+02:00",
    "privileges": 3141499,
    "registered_on": "2016-01-12T06:57:57+01:00",
    "username": "Howl",
    "username_aka": ""
}
http 'https://ripple.moe/api/v1/users?l=2' X-Ripple-Token:<strip>
HTTP/1.1 200 OK
CF-RAY: 2f91497158b43dad-MXP
Connection: keep-alive
Content-Encoding: gzip
Content-Length: 231
Content-Type: application/json; charset=utf-8
Date: Fri, 28 Oct 2016 20:55:07 GMT
Server: cloudflare-nginx
Vary: Accept-Encoding

{
    "code": 200,
    "users": [
        {
            "country": "IT",
            "id": 999,
            "latest_activity": "2016-06-24T13:05:27+02:00",
            "privileges": 3075579,
            "registered_on": "2016-01-11T21:41:20+01:00",
            "username": "FokaBot",
            "username_aka": ""
        },
        {
            "country": "IT",
            "id": 1000,
            "latest_activity": "2016-10-28T22:28:57+02:00",
            "privileges": 3141503,
            "registered_on": "2016-01-11T21:41:20+01:00",
            "username": "Nyo",
            "username_aka": ""
        }
    ]
}
http 'https://ripple.moe/api/v1/users?l=2&sort=donor_expire' X-Ripple-Token:<strip>
HTTP/1.1 200 OK
CF-RAY: 2f91662b8e9e4304-MXP
Connection: keep-alive
Content-Encoding: gzip
Content-Length: 241
Content-Type: application/json; charset=utf-8
Date: Fri, 28 Oct 2016 21:14:44 GMT
Server: cloudflare-nginx
Vary: Accept-Encoding

{
    "code": 200,
    "users": [
        {
            "country": "US",
            "id": 3169,
            "latest_activity": "2016-10-04T22:41:46+02:00",
            "privileges": 6,
            "registered_on": "2016-06-10T11:49:40+02:00",
            "username": "Inverlock",
            "username_aka": ""
        },
        {
            "country": "IT",
            "id": 1012,
            "latest_activity": "2016-08-22T19:26:36+02:00",
            "privileges": 7,
            "registered_on": "2016-01-12T22:36:02+01:00",
            "username": "Pisellone",
            "username_aka": ""
        }
    ]
}
$ http 'https://ripple.moe/api/v1/users?ids=1000&ids=1009&ids=1109' X-Ripple-Token:<strip>
HTTP/1.1 200 OK
CF-RAY: 2f95413a5f6e3dbf-MXP
Connection: keep-alive
Content-Encoding: gzip
Content-Length: 272
Content-Type: application/json; charset=utf-8
Date: Sat, 29 Oct 2016 08:28:34 GMT
Server: cloudflare-nginx
Vary: Accept-Encoding

{
    "code": 200,
    "users": [
        {
            "country": "IT",
            "id": 1000,
            "latest_activity": "2016-10-28T22:28:57+02:00",
            "privileges": 3141503,
            "registered_on": "2016-01-11T21:41:20+01:00",
            "username": "Nyo",
            "username_aka": ""
        },
        {
            "country": "IT",
            "id": 1009,
            "latest_activity": "2016-10-29T10:28:26+02:00",
            "privileges": 3141499,
            "registered_on": "2016-01-12T06:57:57+01:00",
            "username": "Howl",
            "username_aka": ""
        },
        {
            "country": "IL",
            "id": 1109,
            "latest_activity": "2016-10-29T08:17:33+02:00",
            "privileges": 3075579,
            "registered_on": "2016-03-21T15:21:49+01:00",
            "username": "shavit",
            "username_aka": "shavitush"
        }
    ]
}

GET /users/self

Same as GET /users, except that it returns the current user and no parameter must be passed.

Examples

$ http 'https://ripple.moe/api/v1/users/self' X-Ripple-Token:<strip>
HTTP/1.1 200 OK
CF-RAY: 2f95b60aeeba3d8f-MXP
Connection: keep-alive
Content-Encoding: gzip
Content-Length: 174
Content-Type: application/json; charset=utf-8
Date: Sat, 29 Oct 2016 09:48:19 GMT
Server: cloudflare-nginx
Vary: Accept-Encoding

{
    "code": 200,
    "country": "IT",
    "id": 1009,
    "latest_activity": "2016-10-29T11:42:52+02:00",
    "privileges": 3141499,
    "registered_on": "2016-01-12T06:57:57+01:00",
    "username": "Howl",
    "username_aka": ""
}

GET /users/full

Retrieves all the possible information about an user.

Parameters

Name Description Required?
id The User ID of the user you're looking for. Only if name is not given
name The username of the user you're looking for. Only if id is not given

Response

Inherits all the fields of User, and adds this:

Field name Type Value
std ModeStats Mode stats for osu! standard.
taiko ModeStats Mode stats for Taiko.
ctb ModeStats Mode stats for Catch the Beat.
mania ModeStats Mode stats for osu!mania.
play_style int Play style for this user. See Play style
favourite_mode int Favourite mode of the user, that can be set in the settings. It's the mode that should be shown by default.
badges []Badge Array containing the badges of the user.
custom_badge *Badge If the user is a donor and has set a custom badge, it will be shown here. Does not contain the field id. (null-able)
silence_info.reason string Reason why this user was silenced.
silence_info.end time Datetime the user's silence will be removed.

Examples

$ http --pretty=colors 'https://ripple.moe/api/v1/users/full?id=1009' X-Ripple-Token:<strip>
HTTP/1.1 200 OK
Date: Sat, 29 Oct 2016 08:48:37 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 575
Connection: keep-alive
Content-Encoding: gzip
Vary: Accept-Encoding
Server: cloudflare-nginx
CF-RAY: 2f955e984d06430a-MXP

{
    "code": 200,
    "id": 1009,
    "username": "Howl",
    "username_aka": "",
    "registered_on": "2016-01-12T06:57:57+01:00",
    "privileges": 3141499,
    "latest_activity": "2016-10-29T10:28:26+02:00",
    "country": "IT",
    "std": {
        "ranked_score": 561601521,
        "total_score": 1507798195,
        "playcount": 1104,
        "replays_watched": 7,
        "total_hits": 52509,
        "level": 61.17723833993767,
        "accuracy": 97.659744,
        "pp": 2147,
        "global_leaderboard_rank": 1418
    },
    "taiko": {
        "ranked_score": 0,
        "total_score": 12352,
        "playcount": 1,
        "replays_watched": 0,
        "total_hits": 0,
        "level": 1.411713723790793,
        "accuracy": 0,
        "pp": 0,
        "global_leaderboard_rank": 10009
    },
    "ctb": {
        "ranked_score": 1751854,
        "total_score": 2095274,
        "playcount": 5,
        "replays_watched": 1,
        "total_hits": 1633,
        "level": 7.062165714285714,
        "accuracy": 98.13169,
        "pp": 0,
        "global_leaderboard_rank": 708
    },
    "mania": {
        "ranked_score": 1055577,
        "total_score": 3256243,
        "playcount": 19,
        "replays_watched": 0,
        "total_hits": 224,
        "level": 8.12959044117647,
        "accuracy": 81.68839,
        "pp": 1,
        "global_leaderboard_rank": 2566
    },
    "play_style": 255,
    "favourite_mode": 0,
    "badges": [
        {
            "id": 2,
            "name": "Developer",
            "icon": "fa-code"
        }
    ],
    "custom_badge": {
        "name": "KAFFÈÈE??",
        "icon": "fa-coffee"
    },
    "silence_info": {
        "reason": "",
        "end": "2016-06-18T23:15:12+02:00"
    }
}

GET /users/whatid

Retrieves an ID of an user, knowing their username. Simple as that.

Examples

$ http 'https://ripple.moe/api/v1/users/whatid?name=Howl' X-Ripple-Token:<strip>
HTTP/1.1 200 OK
CF-RAY: 2f95a0965cb4435e-MXP
Connection: keep-alive
Content-Encoding: gzip
Content-Length: 51
Content-Type: application/json; charset=utf-8
Date: Sat, 29 Oct 2016 09:33:40 GMT
Server: cloudflare-nginx
Vary: Accept-Encoding

{
    "code": 200,
    "id": 1009
}

GET /users/userpage

Retrieve the userpage of an user, in BBCode.

Parameters

Name Description Required?
id The User ID of the user of which userpage you're looking for. Only if name is not given
name The username of the user of which userpage you're looking for. Only if id is not given

Examples

$ http 'https://ripple.moe/api/v1/users/userpage?id=1009' X-Ripple-Token:<strip>
HTTP/1.1 200 OK
CF-RAY: 2f95a5ecbfa6430a-MXP
Connection: keep-alive
Content-Encoding: gzip
Content-Length: 496
Content-Type: application/json; charset=utf-8
Date: Sat, 29 Oct 2016 09:37:18 GMT
Server: cloudflare-nginx
Vary: Accept-Encoding

{
    "code": 200,
    "userpage": "[left][size=7]Hi![/size]\r\n[size=3][color=#555555]I'm Howl. Probably the most memetastic individual you'll ever meet.[/color][/size]\r\n\r\n[size=3]I pretty much write blog posts and write lots of code for Ripple. I mainly work on the non-osu! related stuff, such as the website and the API, although I do occasionally do small contributions to other projects.[/size]\r\n\r\n[size=3]Writing code is my jam, especially in Go. I accidentally also know how to write in PHP, JS, C#, bash, Python, CSS, HTML.[/size]\r\n\r\n[size=3]You can contact me by sending an email at either [email=howl@ripple.moe]howl@ripple.moe[/email] or [email=the@howl.moe]the@howl.moe[/email].\r\n[/size][/left]\r\n\r\n[container width=100][youtube]OPf0YbXqDm0[/youtube][/container]"
}

GET /users/lookup

Search for an user knowing (part of) their username. This is mainly used for Ripple's user search function, in the navbar.

Parameters

Name Description Required?
name (Part of) the username. Yes

Examples

$ http 'https://ripple.moe/api/v1/users/lookup?name=Sha' X-Ripple-Token:<strip>
HTTP/1.1 200 OK
CF-RAY: 2f95ae2b2cc9430a-MXP
Connection: keep-alive
Content-Encoding: gzip
Content-Length: 360
Content-Type: application/json; charset=utf-8
Date: Sat, 29 Oct 2016 09:42:56 GMT
Server: cloudflare-nginx
Vary: Accept-Encoding

{
    "code": 200,
    "users": [
        {
            "id": 1006,
            "username": "Shaural"
        },
        {
            "id": 1109,
            "username": "shavit"
        },
        {
            "id": 1382,
            "username": "Shalltear"
        },
        {
            "id": 1448,
            "username": "ByArqasha"
        },
        {
            "id": 1585,
            "username": "Intusha"
        },
        {
            "id": 1590,
            "username": "forcesha"
        },
        {
            "id": 1854,
            "username": "mishanya"
        },
        {
            "id": 1869,
            "username": "Yasha3471"
        },
        ...
    ]
}

Manage users

POST /users/edit

Edit an user's information, such as username, email, etc.

JSON fields

Field Type Description Required?
id int The ID of the user to edit. Yes
username string New username of the user. No
username_aka string New username_aka of the user. No
country string New country of the user. No
reset_userpage bool Whether to reset the userpage. No
silence_info.reason string Reason why this user was silenced. No
silence_info.end time Datetime the user's silence will be removed. No

All the fields except for id are optional, and if they are not passed they will not be modified.

Response

The edited User. The username field may not immediately show up as edited, because changing an username may take several seconds, due to gracefully handling the case where an user is logged into osu!.

Examples

$ http https://ripple.moe/api/v1/users/edit X-Ripple-Token:197c0b6ba75cdbc5121cb23cf8ba04ee id:=1002 username_aka=yay1123 country=IT
HTTP/1.1 200 OK
Content-Encoding: gzip
Content-Length: 171
Content-Type: text/plain; charset=utf-8
Content-Type: application/json; charset=utf-8
Date: Sun, 25 Feb 2018 10:57:04 GMT
Server: fasthttp
Vary: Accept-Encoding

{
    "code": 200,
    "country": "IT",
    "id": 1002,
    "latest_activity": "1970-01-01T01:00:00+01:00",
    "privileges": 3,
    "registered_on": "2016-12-08T12:00:06+01:00",
    "username": "user3",
    "username_aka": "yay1123"
}

POST /users/wipe

Remove all scores made by a given user in a given set of gamemodes.

JSON fields

Field Type Description Required?
id int The ID of the user to edit. Yes
modes []int Modes for which the scores of the user should be reset. Yes

Response

The User.

Examples

$ http https://ripple.moe/api/v1/users/wipe X-Ripple-Token:197c0b6ba75cdbc5121cb23cf8ba04ee id:=1002 modes:='[0]'
HTTP/1.1 200 OK
Content-Encoding: gzip
Content-Length: 167
Content-Type: text/plain; charset=utf-8
Content-Type: application/json; charset=utf-8
Date: Sun, 25 Feb 2018 10:29:43 GMT
Server: fasthttp
Vary: Accept-Encoding

{
    "code": 200,
    "country": "XX",
    "id": 1002,
    "latest_activity": "1970-01-01T01:00:00+01:00",
    "privileges": 3,
    "registered_on": "2016-12-08T12:00:06+01:00",
    "username": "user3",
    "username_aka": ""
}

Scores

GET /scores

Retrieves scores for a certain beatmap. Implements pagination.

Parameters

Name Description Required?
md5 The md5 hash of the requested beatmap. Only if b is not passed
b The beatmap ID. Only if md5 is not passed
mode Mode of which the scores must be. If not passed, scores from all modes are returned. No

Sorting

Field Description
pp ...
score ...
accuracy ...
id Use ID to fetch scores in (reverse) chronological order.

Response

scores being a []Score. In the scores there's also the field user, containing an User, which is the user who made the score.

Examples

http 'https://ripple.moe/api/v1/scores?b=75&l=2&mode=0' X-Ripple-Token:<strip>
HTTP/1.1 200 OK
CF-RAY: 2f969a5c0ca60e42-MXP
Connection: keep-alive
Content-Encoding: gzip
Content-Length: 473
Content-Type: application/json; charset=utf-8
Date: Sat, 29 Oct 2016 12:24:10 GMT
Server: cloudflare-nginx
Vary: Accept-Encoding

{
    "code": 200,
    "scores": [
        {
            "accuracy": 100,
            "beatmap_md5": "a5b99395a42bd55bc5eb1d2411cbdf8b",
            "completed": 3,
            "count_100": 0,
            "count_300": 194,
            "count_50": 0,
            "count_geki": 45,
            "count_katu": 0,
            "count_miss": 0,
            "full_combo": true,
            "id": 629651,
            "max_combo": 314,
            "mods": 88,
            "play_mode": 0,
            "pp": 166.3,
            "score": 1854375,
            "time": "2016-10-21T00:49:02+02:00",
            "user": {
                "country": "US",
                "id": 7880,
                "latest_activity": "2016-10-29T12:34:56+02:00",
                "privileges": 7,
                "registered_on": "2016-08-08T22:13:00+02:00",
                "username": "Jash",
                "username_aka": ""
            }
        },
        {
            "accuracy": 96.563576,
            "beatmap_md5": "a5b99395a42bd55bc5eb1d2411cbdf8b",
            "completed": 3,
            "count_100": 10,
            "count_300": 184,
            "count_50": 0,
            "count_geki": 38,
            "count_katu": 7,
            "count_miss": 0,
            "full_combo": true,
            "id": 485504,
            "max_combo": 314,
            "mods": 80,
            "play_mode": 0,
            "pp": 82.9,
            "score": 1692113,
            "time": "2016-09-22T17:55:44+02:00",
            "user": {
                "country": "DE",
                "id": 9464,
                "latest_activity": "2016-10-23T19:22:24+02:00",
                "privileges": 3,
                "registered_on": "2016-08-24T18:24:52+02:00",
                "username": "enjoy game",
                "username_aka": ""
            }
        }
    ]
}
http 'https://ripple.moe/api/v1/scores?b=75&l=2&mode=1' X-Ripple-Token:<strip>
HTTP/1.1 200 OK
CF-RAY: 2f96a3148a8a3db9-MXP
Connection: keep-alive
Content-Encoding: gzip
Content-Length: 375
Content-Type: application/json; charset=utf-8
Date: Sat, 29 Oct 2016 12:30:08 GMT
Server: cloudflare-nginx
Vary: Accept-Encoding

{
    "code": 200,
    "scores": [
        {
            "accuracy": 91.10577,
            "beatmap_md5": "a5b99395a42bd55bc5eb1d2411cbdf8b",
            "completed": 3,
            "count_100": 29,
            "count_300": 175,
            "count_50": 0,
            "count_geki": 0,
            "count_katu": 0,
            "count_miss": 4,
            "full_combo": false,
            "id": 539660,
            "max_combo": 127,
            "mods": 0,
            "play_mode": 1,
            "pp": 0,
            "score": 227530,
            "time": "2016-10-04T22:53:39+02:00",
            "user": {
                "country": "IT",
                "id": 1113,
                "latest_activity": "2016-10-28T22:48:45+02:00",
                "privileges": 3,
                "registered_on": "2016-03-21T16:10:40+01:00",
                "username": "Nevy",
                "username_aka": "A nice guy :)"
            }
        }
    ]
}

GET /users/scores/recent, GET /users/scores/best

These two methods are almost the same, except that /recent sorts scores in reverse chronological order and also returns non-ranked scores while /best sorts scores by PP or score if PP is not available for a certain mode and only returns ranked scores. Implements pagination (1 < x <= 100).

Parameters

Name Description Required?
id The User ID of the user of which scores you're looking for. Only if name is not given
name The username of the user of which scores you're looking for. Only if id is not given
mode Mode of which the scores must be. If not passed, scores from all modes are returned. No

Response

An array of Scores, with the additional field beatmap of type Beatmap giving more information on the beatmap played.

Examples

$ http 'https://ripple.moe/api/v1/users/scores/recent?name=Howl&mode=3' X-Ripple-Token:<strip>
HTTP/1.1 200 OK
CF-RAY: 2f975d1a7f7d0e30-MXP
Connection: keep-alive
Content-Encoding: gzip
Content-Length: 632
Content-Type: application/json; charset=utf-8
Date: Sat, 29 Oct 2016 14:37:07 GMT
Server: cloudflare-nginx
Vary: Accept-Encoding

{
    "code": 200,
    "scores": [
        {
            "id": 67151,
            "beatmap_md5": "95edfcd2295b42b8ce69158ec367a1cb",
            "score": 500237,
            "max_combo": 159,
            "full_combo": false,
            "mods": 0,
            "count_300": 169,
            "count_100": 24,
            "count_50": 12,
            "count_geki": 127,
            "count_katu": 83,
            "count_miss": 28,
            "time": "2016-05-30T19:38:31+02:00",
            "play_mode": 3,
            "accuracy": 81.56509,
            "pp": 0.986275,
            "completed": 3,
            "beatmap": {
                "beatmap_id": 315293,
                "beatmapset_id": 123456,
                "beatmap_md5": "95edfcd2295b42b8ce69158ec367a1cb",
                "song_name": "Lite Show Magic - Crack traxxxx [4K NOV]",
                "ar": 5,
                "od": 7,
                "difficulty": 0,
                "difficulty2": {
                    "std": 0,
                    "taiko": 0,
                    "ctb": 0,
                    "mania": 1.6707656
                },
                "max_combo": 0,
                "hit_length": 113,
                "ranked": 2,
                "ranked_status_frozen": 0,
                "latest_update": "2016-10-22T17:29:38+02:00"
            }
        },
        {
            "id": 1546,
            "beatmap_md5": "2726628f508221dacf8d38c3f2c49344",
            "score": 555340,
            "max_combo": 35,
            "full_combo": false,
            "mods": 0,
            "count_300": 18,
            "count_100": 1,
            "count_50": 0,
            "count_geki": 24,
            "count_katu": 4,
            "count_miss": 8,
            "time": "2016-02-12T18:44:55+01:00",
            "play_mode": 3,
            "accuracy": 81.818184,
            "pp": 0.223737,
            "completed": 3,
            "beatmap": {
                "beatmap_id": 647965,
                "beatmapset_id": 281349,
                "beatmap_md5": "2726628f508221dacf8d38c3f2c49344",
                "song_name": "Drop - Granat [5K Easy]",
                "ar": 9,
                "od": 7,
                "difficulty": 0,
                "difficulty2": {
                    "std": 0,
                    "taiko": 0,
                    "ctb": 0,
                    "mania": 0.8195409
                },
                "max_combo": 0,
                "hit_length": 41,
                "ranked": 2,
                "ranked_status_frozen": 0,
                "latest_update": "2016-10-21T04:20:16+02:00"
            }
        }
    ]
}
http --pretty=colors 'https://ripple.moe/api/v1/users/scores/best?id=999&mode=0&l=2' X-Ripple-Token:<strip>
HTTP/1.1 200 OK
Date: Sat, 29 Oct 2016 14:47:05 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 643
Connection: keep-alive
Content-Encoding: gzip
Vary: Accept-Encoding
Server: cloudflare-nginx
CF-RAY: 2f976bb1b9de430a-MXP

{
    "code": 200,
    "scores": [
        {
            "id": 20680,
            "beatmap_md5": "33c79fe1085fb53714149df535286753",
            "score": 358628,
            "max_combo": 143,
            "full_combo": true,
            "mods": 64,
            "count_300": 79,
            "count_100": 8,
            "count_50": 0,
            "count_geki": 15,
            "count_katu": 5,
            "count_miss": 0,
            "time": "2016-04-23T18:47:01+02:00",
            "play_mode": 0,
            "accuracy": 93.86973,
            "pp": 55.34,
            "completed": 3,
            "beatmap": {
                "beatmap_id": 665129,
                "beatmapset_id": 295480,
                "beatmap_md5": "33c79fe1085fb53714149df535286753",
                "song_name": "yes we cant - wh [Hard]",
                "ar": 7,
                "od": 6,
                "difficulty": 2.8608754,
                "difficulty2": {
                    "std": 2.8608754,
                    "taiko": 2.58527,
                    "ctb": 1.6264615,
                    "mania": 1.6862342
                },
                "max_combo": 143,
                "hit_length": 35,
                "ranked": 2,
                "ranked_status_frozen": 0,
                "latest_update": "2016-10-28T22:25:48+02:00"
            }
        },
        {
            "id": 13042,
            "beatmap_md5": "4714b140830082baa76db4269922de57",
            "score": 107178,
            "max_combo": 80,
            "full_combo": false,
            "mods": 1,
            "count_300": 101,
            "count_100": 11,
            "count_50": 1,
            "count_geki": 17,
            "count_katu": 11,
            "count_miss": 4,
            "time": "2016-04-08T18:04:14+02:00",
            "play_mode": 0,
            "accuracy": 89.60114,
            "pp": 20.49,
            "completed": 3,
            "beatmap": {
                "beatmap_id": 663819,
                "beatmapset_id": 295480,
                "beatmap_md5": "4714b140830082baa76db4269922de57",
                "song_name": "yes we cant - wh [Gerawak's Insane]",
                "ar": 9,
                "od": 7.5,
                "difficulty": 4.056512,
                "difficulty2": {
                    "std": 4.056512,
                    "taiko": 3.3383908,
                    "ctb": 3.231594,
                    "mania": 1.97748
                },
                "max_combo": 205,
                "hit_length": 35,
                "ranked": 2,
                "ranked_status_frozen": 0,
                "latest_update": "2016-10-21T21:27:12+02:00"
            }
        }
    ]
}