ppy/osu-api

Public API for accessing osu! related data.

osu-api

Public API for accessing osu! related data.

See the wiki for more details.

osu-api's Issues

[Future Request] Expanding API

Would be nice to add these in future:

/get_user/ :
-create_date
-last_seen (maybe, dunno?)
-max_combo (probably not needed, but still)
-watched_replays
-historical [array of most played beatmaps]
-uploaded beatmaps (would be nice for mappers, but can be used in /get_beatmaps/

Reason is because currently these values can be retrieved only from HTML-parsing.

/api/get_beatmaps returns "null"

Both with the "since" parameter and the "s" parameter /api/get_beatmaps returns just the word "null" (without quotation marks) on any request.
If no key is used I still get the "no valid key" message.

Note: I am using the key of osu!tp

Obtain per-HitObject data about miss, 50, 100 and 300 of individual scores

If this is stored somewhere it would be nice to be able to access it.
My use case is tp. Since beatmap difficulty is represented in strain values per HitObject it would enable me to weight scores based on how well the hard parts were performed and would greatly increase the algorithm's accuracy on maps with large and short difficulty spikes.

( get_match ) add a search for match

I need to take the match using the name of match, for me there are two way:

Add parameters

mp = all
(return all active matches)

Or adding a search api

/api/search_match/

n = Name
k = key

Return: Array of match found

I need this for a ladder project, i'll take the match which starts with "[ladder]"

More data for get_user?

Hey,

I'm the lead developer for https://github.com/gdude2002/Pippi - an IRC bot that's designed to work with the main Osu! site and provide various integrations with it.

Now, at the moment, all it can do is take a /b/ or /s/ URL and return some info on it. It does this by using a scraper I wrote in Django (Sorry!). Now, your API will make this stuff a lot easier, faster, and more above-board, and for the purposes of grabbing info from URLs, it's plenty for that.

However, we're looking to add some notifications while people are playing - For example, if someone achieves a toprank, or even something akin to the "Recent activity" section on the current player pages; perhaps checking the API every so often and posting a message like "User X earned rank Y on map Z".

Are there any plans to add something like this to the API?

Thanks,
Gareth

API too slow?

"Current rate limit is set at an insanely high 1200 requests per minute"
That's what is written in docs.
But it doesn't seem like it's correct. Using my updater(osuStats) script I can get at most 200maps(requests)/1min with is way lower ratio than in docs. (Now update takes about 9-10hrs(all modes) instead of ~30-40mins before API keys were introduced- no changes were made in my script(only hardcoding apikey))

showing free mods of match

I can't find free mods of a match in the API and it should be available.

Online Status for user

I've mentioned that /api/get_user can't get a player's online status ,and some online signatures can be better with this.

no data with old graveyard beatmaps

I found that get_beatmaps gives me no data when I request for an old beatmap.
http://osu.ppy.sh/s/12462 , this beatmap isn't deleted but api says "It is deleted!"

count200 on /get_users Mania mode

In the Mania game mode of Osu! there is a 200 hit count which is displayed while playing and at the end of game when it shows the results

but in the API it only shows the 300 hit count, 100 hit count, and 50 hit count.
So where are the 200?

Is it merged with the 300 (because i ever test to sum all 300+100+50 hit count as total hit, it same as my total hit on user profile)? ... or is not even showed?

Image link (id) for /get_beatmaps

Basically, I would like to provide on my page that fancy little image thumbnail, but I don't want to scrap page for it, is it possible to add?

Expanding /get_user/

Hello.

I would love to see this additional elements in /get_user/ call:

• best_scores - top 50 scores (maybe less, or a bit more?), and each one contains:
  • beatmap_id - id for beatmap played;
  • rank - rank for the play - SS, X, SH, S, A, B, C or D;
  • pp - pp for the play, unweighted;
  • pp_weighted - pp for the play, weighted (or percentage for play);
  • date - date for the play.
  • mods - mods applied.
  • accuracy - accuracy for the play - for example, 99,97

It would allow people for a lot of things, that aren't at the moment possible without a website scraper (for example, analyzing best beatmaps of people).

Cheers,
maciej01

Add 'supporter' field for get_user

As part of an IRC bot I'm currently making for an #osu channel on another IRC server, I'm allowing users to get info about other users stats (i.e. rank, score, playedcount, etc). One thing that I'm currently doing via XML and using the site is finding out whether or not a user is a supporter. I'd like to do that with the API as well, but it seems it isn't supported.

Would it be possible to add this to the API?

Searching Users/Beatmaps

As an osu-api enabled application I want to be able to search through users/beatmaps at least as effectively as I can on the osu! website.

So searching for users by partial name (similarly to the autocomplete when searching users on the website shows names that are close).

And Searching beatmaps by all or most of the search criteria available on osu.ppy.sh/p/beatmaplist

--Edit-- Postponed until someone has an real use for it. Just add a comment if you plan on using this feature should it be implemented.

Checking "with video" on get_beatmaps

By testing the API for getting the beatmap info, I haven't found any way on how to know if there is a video included or not. Would it be better to add it?

Like "video"="1" if there is a video available (and "0" if not).

/get_beatmaps exclude 3 years of ranked maps

Dear ppy,
atm im rewritting the osustats bot in node.js. But the api jumps from 2009-07-07 06:54:23 to 2011-11-16 07:53:06 (http://puu.sh/6vtSB.png). Many beatmaps are missing now and with them the ids to retrieve the scores for osustats. Any chance to fix that on your side ? (our side is ok) Did GET request with Postman for Chrome with these settings (http://puu.sh/6vuat.png) same issue with Piotrekols API key.

sincerely Ezoda

Expanding beatmap API

Would be nice to add these in future:

beatmap :
max combo(it's difficult for me to calculate accurately)
circle count
slider count
spinner count
ar/cs/od/hp of a map

/api/get_user add parameters

I think it's good to add these parameters:

-from (player id)
-to (player id)

if you want to take the full list of players without making too many queries

example:

/get_user?k=xxx&from=0&to=500

response:

[ [ {player 0 mode 0} {player 0 mode 1} ... ] .... [player 1] ... ]

or if there is a better way ... I'd need to have all the information about all the players to create the charts ^^

my site works like this:

sample data players (from osu server) ----> our database (every 24 hours)

database ---> processing ---> Profile

/api/get_beatmaps returns "null" on "b" parameter

Same issue as before, only with the "b" parameter, though.

Tested with b=75 (ranked) and b=119431 (graveyard), using the key of osu!tp.

Last update time further than approved time? Reranked maps issue.

I have been trying to update wiki, to add entries about new responses, and I've come to the problem

    "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 

Map was unranked due to bad title, and has been reranked later, that means beatmap was updated AFTER first rank, however approved_date shows old approve date, and therefore differs from update time (what I mean, last_update should be in most cases BEFORE approved_date)

Beatmap used: http://osu.ppy.sh/forum/t/132678/start=60

/get_beatmaps additional information

/get_beatmaps lacks of metadata that can be useful for advanced analysis (used for stuff such as Ranking Charts creation)

Requesting API ends for fetching Online Favorites count per set, Average User Rating per set, playcount (attempts to pass a map) per difficulty, passcount (successful passes) per difficulty.

Change [event_days] behavior of api/get_user

Greetings,

currently you can fetch the last user events in days, but it would be nice to either turn it off completely, by handing a 0 to event_days for example or to add another (optional) parameter event_count or max_events which controls the actual count of events.

"Why do you need this?"
Well, I want to add the ability to turn it off as it would redouce the dataload of the device, in my case phone for example.

"You could just set it to 1, its just all events of one day."
True, but it could happen that a user created a lot of events every day, so this won't fix it, as its only limiting time, not the count.

Regards,

-givenameplz

get_user - Getting user by last used ip address?

I'm having a php counter, which counts how many times profile has been accessed (via userpage, similar to flag fag counter) from where user is, and how many times been on profile. However, I'd like to add a functionality, to know WHO exactly was that, rather than having just IP's. Since, sometimes people want to stay anonymous, and some not, it's not really high priority to add into API, however I'd really appreciate something like this being able to do.

/get_user returns data in players when it shouldn't

Apparently doing a query to players that only played in osu!mania before the score reset return "full data" when it shouldn't.

Winshley told me that in my "application" when viewing the osu!mania stats, his were borked, but that's actually a problem in my end. The case here is that I get his osu!mania stats while viewing his profile shows that "he hasn't played" the mode after the score reset.

Here's the data that I received when querying his osu!mania stats:

Array
(
    [0] => Array
        (
            [user_id] => 864895
            [username] => Winshley
            [count300] => 7164
            [count100] => 23
            [count50] => 12
            [playcount] => 338
            [ranked_score] => 0
            [total_score] => 144063600
            [pp_rank] => 0
            [level] => 28.0984
            [pp_raw] => 0
            [accuracy] => 0
            [country] => ID
        )

)

I was expecting the API to return an empty list like with players that actually haven't played the mode at all or this is actually intended behavior?

user events from past hour / day

/api/get_user
provides "events" and contains the five latest events for this user

It would be better if the api provided all events from a fixed period of time, e.g. the last hour or day at the moment of the request.

This would allow me to complete a news feed.
Even better would be a way to subscribe via rss, if that's not too much off topic here.

And if I may extend even further: allow to get stats for multiple users in one request, to reduce the number of requests made.

end_time of match always null (/api/get_match)

Just tested API, played two matches, on both matches after all players leave end_time is null.

https://osu.ppy.sh/mp/1952427
https://osu.ppy.sh/mp/1936471

Querying these IDs returns null on this field.

Can't get 2010 maps.

When i wanted to get a full list of beatmaps, i found that most beatmaps ranked between 2009-07-07 and 2011-11-16 are invisible.
I got this when i used this query string:
https://osu.ppy.sh/api/get_beatmaps?k=<api_key>&since=2009-5-24%200:0:0

{"beatmapset_id":"7884","beatmap_id":"33227","approved":"1","approved_date":"2009-07-07 06:54:23","last_update":"2009-07-07 06:34:58","total_length":"104","hit_length":"85","version":"Normal","artist":"Katy Perry","title":"Waking Up in Vegas","creator":"Takuma","bpm":"131","source":"","difficultyrating":"4.33724","mode":"0"},{"beatmapset_id":"12177","beatmap_id":"95804","approved":"1","approved_date":"2011-11-16 07:53:06","last_update":"2011-11-14 02:28:47","total_length":"145","hit_length":"143","version":"Insane","artist":"3rd Coast (Arranged by Forte escape)","title":"My jealousy","creator":"Rena-chan","bpm":"130","source":"DJMAX","difficultyrating":"4.93079","mode":"0"},

Last Ranked/Approved and Last Pending beatmap of a user

Would it be possible to grab the last ranked/approved and the last pending beatmap along with the date they were ranked(or approved) for the ranked/approved beatmap and the date it was submitted for the pending beatmap for a specific user ID.

The reason I would like this I am currently making a website on which users can subscribe to their favourite mappers and how long ago the last ranked/approved beatmap was ranked and the last pending beatmap was submitted to see if any of their favourite mappers have any new maps. The problem is the current way of doing this is to get all the information from the user's profile to find the beatmaps and then to get all the information from the page of each beatmap to find the last submitted date for pending beatmaps and the ranked date for ranked/approved beatmaps.

/api/get_users

Getting a user list sorted by sortable columns like user_id,playcount,ranked_score,total_score,pp,accuracy,ss,s,a,last_active
And it's better if we can set limits, like " last_active>'2013-12-04' ","SS>1000"

Bug: empty string returned by /get_user for usernames made of numbers only

Hi,

Each time I try to fetch information for this user: http://osu.ppy.sh/u/119410501, I get an empty string from /get_user. The thing is, he does have stats in every mode, so the string shouldn't be empty.
My best guess is that the API is trying to get info from user ID 119410501 while it should get info from username 119410501.

Edit: seems it can be replicated with all numbers-only usernames. Another example: https://osu.ppy.sh/u/670839245 (empty string as well)

XPJ38

Additional /api/get_user responses

I'll just get to the point on this one. /api/get_user can use some more responses and here's what I'm thinking.

1. More than 5 events in the response, I'm saying this because profile page on the site provide more events information than the API does
2. Achievements
3. Infringements
4. Historical stuff, such as most played maps and recent plays
5. User's beatmaps
6. Kudosu

These are just my suggestions so far. Thanks for listening.

Not getting every result for maps

Thanks a lot peppy for the last fix! I've been able to solve pretty much all my problems with it! I only have one slight problem remaining, when I get all the maps for a specific user, if the user has a lot of maps (e.g. Andrea) then it only fetches a certain amount and not all of them. I was wondering if you could help with this?
Thanks a lot!

Last update time for unranked maps (or all?) /api/get_beatmaps

Basically title, since I'm planning to use api for my own project, and having this would be really useful, to distinguish which version of beatmap has been added to my system.

(get_match) Match name differs from mp link

I have been trying to parse one of my matches using my own functions, and while trying to regex the match name, but... sadly API returns different result than mp link.

https://osu.ppy.sh/mp/2405552
vs
https://osu.ppy.sh/api/get_match?k=key&mp=2405552

Is it possible to fix? I guess this problem occurred because I had first name for like 10 minutes before starting first match.

/get_user improvement: return non-empty string is user exists

Currently, /get_user returns an empty string in two cases:

• The user or ID provided does not exist,
• User has no stats at all in the selected mode (i.e. never played at all). Example: Cookiezi on osu!mania.

Request: I would like this behaviour to change. I propose to return a non-empty string if the user exists in database. It would be a string similar to a regular one containing at least the user_id, username and country (i.e. general information about the user), but the other fields would be empty or non-existent. If the user does not exist, an empty string would be returned, as usual.

Use case: I own osusignature.x10.mx, a website that let people create their own dynamic signatures to use in forums or user pages. One of them is a replica of the in-game user panel. Currently, if a user exists but has no stats in the selected mode, an error message is displayed ("no stats in this mode or invalid username"). I'd like instead to display a valid image—with username and avatar, but with the mention "Never played", exactly as it would appear in game.
Generally speaking, I'd like to show a valid image instead of an imprecise error message if user has no stats in one or every mode.

Plays and Success Rate in get_beatmaps

Is it feasible?

Multiplayer match API (api/get_matchinfo)

Since my website is going to be basically new kind of ranking (NEW kind, it's going to be TAG scoreboard) and I'm planning to do automatic score submission etc. But first of all I'm working toward having a way to receive multiplayer match information. I already know there is https://osu.ppy.sh/mp/xxxx but I don't really want to do HTML scrapping on it.
Can you please provide an API for getting score match info?
What I basically need is:
-Who played match (along with their scores, acc, combo, etc.)
-What kind of match it was (Team vs Team, Head to head)
-What map was played.

The website is almost working, it only lacks this one core function (and lacks of good designing, but that's unrelated).
EDIT: Additional thing - having version of beatmap (hash, or date of last update as asked in previous issue) would be really useful.

Expand api: get_score

Can you make visible the record up to 500 in get_score?

I need it to associate the recent activity on the scores

Banned players shown in API.

Hello,

banned players (e.g. Rain - ID: 865724) started appearing in /api/get_user . A quick and dirty fix for detecting bans is to check count300 (or other values) for null, but I'm not sure if that works for all cases.

Could they be either hidden again or could there be some other way to detect this reliably?

Thanks.

"since" parameter for score queries

Currently if you want to query for recent scores, you either have to completely check all beatmaps or use https://osu.ppy.sh/pages/include/profile-general.php?u=$id&m=$mode to at least narrow the recent scores down to the scope of a single player.
(Complete top50 API requests still need to be made for every beatmap the player ranked on.)

A "since" parameter like the one in /api/get_beatmaps would solve this issue and at the same time eliminate the need for score queries on every single beatmap on a regular basis to keep a score database up to date.

Get user-specific stats on a beatmap

Unless I'm missing something, you can currently only get the top 50 scores on a beatmap, get a users information, or get a beatmaps information. What I would like is a way to be able to get information on a beatmap relative to a specific user (for example, get user A's score, rank, miss, 30, 100 and 300 count etc., from beatmap B).
What I would like to do is make a comparison app that you can specify 2 users and a beatmap and you can compare the two

/get_beatmaps/ approved returns wrong value

http://puu.sh/7VHoC/e330ee8edf.png as example

First two one should return 0 (Pending)

http://osu.ppy.sh/s/150145
http://osu.ppy.sh/s/134796

Add link to avatar on get_user

It would be a nice addition to be able to get the user's current avatar. This can be used on all kinds of tools, like signature generators, web applications...

get_user: accuracy inconsistencies

I found out that some accuracies returned by osu!api are not matching accuracies displayed on one's profile. For example:

http://osu.ppy.sh/u/1428609 in Catch the Beat:

• osu!api returns 98.76%
• his profile shows 92.08%

http://osu.ppy.sh/u/2677467 in osu!:

• osu!api returns 0%
• his profile shows 86.36%

Everything else is fine, there's only the accuracy having a problem.

Mode information on get_beatmaps

I'd like to know beatmap's mode on get_beatmaps request.
Currently it only gives beatmap's name.
I think it's cool.

Get profile image URL

is there any way I can get the image for a user? for example, mine (failedxyz) would be at http://s.ppy.sh/a/2688103_1388909730.jpg

"b" parameter for /api/get_beatmaps

Currently if you want information about a specific beatmap difficulty you have to know the beatmapset id, which may not always be the case.

Especially when checking non-ranked maps for updates a "b" parameter comes in handy, because the only option is to use website scraping at the moment.

500 Server error; When requesting for full list of beatmaps.

Today I have noticed that HTTP 500 error is returned when request to list all beatmaps is sent. It worked perfectly fine few days ago.

The reason is that I'm requesting for full list of beatmaps is to check if any of my local beatmaps are out of date ( request will be sent once every few hours, so load should not be a big issue ).

How to reproduce it:
Set 'since' parameter to 0.

Login system

It would be useful to be able to implement the osu! user database into third party tools via API. This would allow applications that require an user db to use the one from osu! , making it easier for users (as they don't have to register again), more secure (as emails, passwords and private stuff only needs to be stored in one server) and simpler for developers (making register and login forms way shorter).

Get current song playing by user

I want to add a functionality to a twitch chat bot to display the current song playing by the streamer. It can be done with recent plays (not on the api either) but it's the last completed song, not the current playing. I've read there's no online status on another request but I don't know if this falls in the same category.