Documentation
Global Parameters
These parameters are used for all API calls.
| Type |
Parameters |
Description |
Values |
| required |
key |
API key used for the request. |
API_KEY |
| required |
action |
The requested API function. |
See Below |
Global Errors
| Code |
ERR_ID |
Error Message |
| -1 |
no_action |
No action was requested. |
| -1 |
invalid_key |
Invalid API Key. |
| -1 |
request_flood |
Too many request in the last 1 second(s). |
| -2 |
insufficient_credits |
Insufficient credits for request. |
Actions
Credits
action = credits
Provides the remaining API credits remaining for the specified key along with the IP credits.
Example Request:
http://www.flashflashrevolution.com/api/api.php?key=API_KEY&action=credits
Example Response:
{
"api_key_remaining": 2000,
"api_key_total": 2000,
"api_ip_remaining": 220,
"api_ip_total": 250,
"api_ip_reset_in":1418135476
}
Level Ranks
action = ranks
Provides access to the level ranks for a user. Includes token + legacy files.
| Parameters |
Description |
| userid |
The userid the ranks are being requested for. If used, username should be avoided. |
| username |
The username the rank are being requested for. If used, userid should be avoided. |
Errors
| Code |
ERR_ID |
Error Message |
| -1 |
invalid_user |
Invalid User Specified. |
Example Request:
http://www.flashflashrevolution.com/api/api.php?key=API_KEY&action=ranks&username=Zageron
Example Response (JSON):
{
"user": {
"name": "Zageron",
"id": "1186339"
},
"songs": {
"1": { // <-- This is the level ID.
"info": {
"level": 1,
"genre": 13,
"name": "Terror From Beyond",
"difficulty": 8,
"notes":514,
"length":"2:50"
},
"scores": {
"score": 796700,
"perfect": 514,
"average": 0,
"miss": 0,
"boo": 0,
"combo": 514,
"played": 2,
"timestamp": 1290483615,
"rank": 1
}
},
"2": {
"info": {
"level": 2,
"genre": 13,
"name": "Get on the Move",
"difficulty": 6,
"notes":357,
"length":"3:03"
},
"scores": {
"score": 553350,
"perfect": 357,
"average": 0,
"miss": 0,
"boo": 0,
"combo": 357,
"played": 1,
"timestamp": 1289719055,
"rank": 1
}
},
...
}
}
Recent Games
action = new_recent_games
Provides access to the users last 25 played games as displayed on the daily stats page.
| Parameters |
Description |
| userid |
The userid the ranks being requested for. If used, username should be avoided. |
| username |
The username the rank being requested for. If used, userid should be avoided. |
Errors
| Code |
ERR_ID |
Error Message |
| -1 |
invalid_user |
Invalid User Specified. |
Example Request:
http://www.flashflashrevolution.com/api/api.php?key=API_KEY&action=new_recent_games&username=Zageron
Example Response (JSON):
{
"user": {
"name": "Zageron",
"id": "1186339"
},
"recent": [
{
"userid": 1186339,
"username": "Zageron",
"songname": "Ambient Angels",
"level": 1557,
"score": 339355,
"raw_score": 15120,
"timestamp": 1549766791,
"timestamp_format": "Feb 9, 08:46 PM",
"amazing": 126,
"perfect": 162,
"good": 31,
"average": 0,
"miss": 5,
"boo": 1,
"combo": 174,
"rank": 3173,
"flag": 0,
"flags": []
},
{
"userid": 1186339,
"username": "Zageron",
"songname": "A White Cat Sings Lovely Jazz Waltz",
"level": 2301,
"score": 769865,
"raw_score": 62095,
"timestamp": 1548032391,
"timestamp_format": "Jan 20, 06:59 PM",
"amazing": 474,
"perfect": 636,
"good": 359,
"average": 80,
"miss": 132,
"boo": 292,
"combo": 103,
"rank": 407,
"flag": 12,
"flags": [
{
"type": "Better Score",
"value": 4
},
{
"type": "Better Raw Score",
"value": 8
}
]
},
...
]
}
Old Recent Games (Deprecated)
action = recent_games
Provides access to the users last 10 played games.
| Parameters |
Description |
| userid |
The userid the ranks are being requested for. If used, username should be avoided. |
| username |
The username the rank are being requested for. If used, userid should be avoided. |
Errors
| Code |
ERR_ID |
Error Message |
| -1 |
invalid_user |
Invalid User Specified. |
Example Request:
http://www.flashflashrevolution.com/api/api.php?key=API_KEY&action=recent_games&username=Zageron
Example Response (JSON):
{
"user": {
"name": "Zageron",
"id": "1186339"
},
"recent": [
{
"level": 1949,
"name": "asdfmovie song",
"score": 1977425,
"timestamp": 1421318214,
"perfect": 1270,
"good": 7,
"average": 0,
"miss": 0,
"boo": 0,
"combo": 1277,
"rank": 133
},
{
"level": 2146,
"name": "Kirlian Isles I",
"score": 196850,
"timestamp": 1421318069,
"perfect": 127,
"good": 0,
"average": 0,
"miss": 0,
"boo": 0,
"combo": 127,
"rank": 1
},
...
]
}
Acheievements
action = achievements
Provides access to the users last 50 achievements.
| Parameters |
Description |
| userid |
The userid the ranks are being requested for. If used, username should be avoided. |
| username |
The username the rank are being requested for. If used, userid should be avoided. |
Errors
| Code |
ERR_ID |
Error Message |
| -1 |
invalid_user |
Invalid User Specified. |
Example Request:
http://www.flashflashrevolution.com/api/api.php?key=API_KEY&action=achievements&username=Zageron
Example Response (JSON):
[
{
"username": "Zageron",
"userid": 1186339,
"type": "gamesplayed",
"value": 18000,
"time": 1544072834,
"time_format": "Dec 5, 11:07 PM",
"desc": "18000 Games Played!"
},
{
"username": "Zageron",
"userid": 1186339,
"type": "grandtotal",
"value": 7,
"time": 1509240163,
"time_format": "Oct 28, 08:22 PM",
"desc": "7 Billion Grandtotal!"
},
{
"username": "Zageron",
"userid": 1186339,
"type": "gamesplayed",
"value": 17000,
"time": 1467334302,
"time_format": "Jun 30, 07:51 PM",
"desc": "17000 Games Played!"
}
]
Level Scores
action = level_scores
Provides access to the highscore table of a single level.
| Parameters |
Description |
| level |
The selected level to get highscores for. |
| page |
Which page of scores to retrieve based on the page limit. |
| limit |
The amount of entries per page within a range of 1-10000. If not set, this defaults to 10000. |
Errors
| Code |
ERR_ID |
Error Message |
| -1 |
invalid_level_id |
Invalid Level ID Specified. |
Example Request:
http://www.flashflashrevolution.com/api/api.php?key=API_KEY&action=level_scores&level=3401
Example Response (JSON):
{
"song": {
"id": 3401,
"songname": "NULCTRL",
"note_count": 1026,
"time": "2:26",
"difficulty": 60,
"players": 89
},
"scores": [
{
"id": 1860467,
"username": "Psycast",
"perfect": 1026,
"good": 0,
"average": 0,
"miss": 0,
"boo": 0,
"timestamp": 1658553329,
"raw_score": 51300,
"rank": 1,
"aaaeq": 60
},
...
{
"id": 2076785,
"username": "Azerr",
"perfect": 84,
"good": 8,
"average": 0,
"miss": 12,
"boo": 4,
"timestamp": 1658932923,
"raw_score": 4260,
"rank": 89,
"aaaeq": 0
}
]
}
Leaderboards
action = leaderboards
Provides access to the leaderboards.
| Parameters |
Description |
| page |
Which page of scores to retrieve based on the page limit. |
| limit |
The amount of entries per page within a range of 1-500. If not set, this defaults to 50. |
Errors
| Code |
ERR_ID |
Error Message |
Example Request:
http://www.flashflashrevolution.com/api/api.php?key=API_KEY&action=leaderboards
Example Response (JSON):
{
"scores": [
{
"userid": 2065490,
"username": "play more",
"rating": 113.225,
"avgrank": 9689.2394082,
"grandtotal": 822943810,
"tierpoints": 822943810,
"country": "Niger",
"unique_aaas": 22,
"unique_fcs": 24
},
{
"userid": 2029965,
"username": "AnMaO",
"rating": 111.912,
"avgrank": 9625.75622058,
"grandtotal": 1312088510,
"tierpoints": 1312088510,
"country": "Uruguay",
"unique_aaas": 70,
"unique_fcs": 105
},
{
"userid": 2030068,
"username": "Myuka",
"rating": 111.197,
"avgrank": 9583.82985878,
"grandtotal": 1394454140,
"tierpoints": 1394454140,
"country": "Chile",
"unique_aaas": 33,
"unique_fcs": 43
},
{
"userid": 1982386,
"username": "Matthia",
"rating": 109.911,
"avgrank": 0.98016139879,
"grandtotal": 96638992515,
"tierpoints": 96638992515,
"country": "Germany",
"unique_aaas": 2938,
"unique_fcs": 2944
},
{
"userid": 2056114,
"username": "neptunefun",
"rating": 109.729,
"avgrank": 9703.71009112,
"grandtotal": 676141845,
"tierpoints": 676141845,
"country": "United States of America",
"unique_aaas": 9,
"unique_fcs": 21
}
]
}
Tournament
action = tournament
Provides access to the tournament.
| Parameters |
Description |
| page |
Which page of scores to retrieve based on the page limit. |
| limit |
The amount of entries per page within a range of 1-500. If not set, this defaults to 50. |
Errors
| Code |
ERR_ID |
Error Message |
Example Request:
http://www.flashflashrevolution.com/api/api.php?key=API_KEY&action=tournament
Profile
action = profile
Provides access to the user profile.
| Parameters |
Description |
| userid |
The userid the profile being requested for. If used, username should be avoided. |
| username |
The username the profile being requested for. If used, userid should be avoided. |
Errors
| Code |
ERR_ID |
Error Message |
| -1 |
invalid_user |
Invalid User Specified. |
Example Request:
http://www.flashflashrevolution.com/api/api.php?key=API_KEY&action=profile&username=Psycast
Example Response (JSON):
{
"tag": "",
"userid": "1860467",
"username": "Psycast",
"age": 11.44,
"AAA": 2448,
"FC": 2462,
"usertitle_full": "FFR Veteran",
"usergroup_icon": "http://www.flashflashrevolution.com/images/icons/usergroups/ffr_veteran.png",
"avatar_url": "http://www.flashflashrevolution.com/vbz/customavatars/avatar1860467_5.gif",
"usergroup": "FFR Veteran",
"roles": [
{
"id": 87,
"name": "D7 Elite Keymasher"
},
{
"id": 49,
"name": "FFR Veterans"
}
],
"total_songs": 3519,
"grand_total": 12540874825,
"games": 9236,
"rank": 222,
"avg_rank": 161
}
Top Scores
action = top_scores
Provides access to the users top scores.
| Parameters |
Description |
| userid |
The userid the top scores being requested for. If used, username should be avoided. |
| username |
The username the top scores being requested for. If used, userid should be avoided. |
Errors
| Code |
ERR_ID |
Error Message |
| -1 |
invalid_user |
Invalid User Specified. |
Example Request:
http://www.flashflashrevolution.com/api/api.php?key=API_KEY&action=top_scores&username=Psycast
Example Response (JSON):
{
"user": {
"name": "Psycast",
"id": 1860467
},
"scores": [
{
"song": {
"name": "Magical 8bit Tour",
"song_id": 1313,
"difficulty": 100,
"note_count": 1877
},
"pa": [
1869,
7,
0,
1,
0,
1200
],
"weight": 96.0798906274
},
{
"song": {
"name": "Counter Clockwise Chant Pattern",
"song_id": 1175,
"difficulty": 96,
"note_count": 1423
},
"pa": [
1423,
0,
0,
0,
0,
1423
],
"weight": 96
},
{
"song": {
"name": "Cest What",
"song_id": 2696,
"difficulty": 96,
"note_count": 1556
},
"pa": [
1556,
0,
0,
0,
0,
1556
],
"weight": 96
},
...
]
}
Users
action = users
Provides access to the user lookup.
| Parameters |
Description |
| name[] |
A multiform array of usernames. |
Errors
| Code |
ERR_ID |
Error Message |
Example Request:
http://www.flashflashrevolution.com/api/api.php?key=API_KEY&action=users&name[]=Psycast&name[]=Velocity
Example Response (JSON):
{
"users": {
"Psycast": 1860467,
"Velocity": 249481
}
}
Song List
action = songlist
Provides access to the game song metadata.
| Parameters |
Description |
| levelid |
Optional: If set, returns only the single level specified. |
Errors
| Code |
ERR_ID |
Error Message |
Example Request:
http://www.flashflashrevolution.com/api/api.php?key=API_KEY&action=songlist
Example Response (JSON):
[
{
"id": 1,
"name": "Terror From Beyond",
"author": "Digital Explosion",
"author_url": "https://ffr.fandom.com/wiki/Digital_Explosion",
"stepauthor": "Synthlight",
"genre": 13,
"difficulty": 12,
"length": "2:50",
"note_count": 514,
"min_nps": 1,
"max_nps": 8,
"timestamp": 1035349200,
"timestamp_format": "Oct 23 2002",
"swf_version": 1675121154
},
{
"id": 2,
"name": "Get on the Move",
"author": "Antinomie",
"author_url": "https://ffr.fandom.com/wiki/Antinomie",
"stepauthor": "Synthlight",
"genre": 13,
"difficulty": 10,
"length": "3:03",
"note_count": 357,
"min_nps": 1,
"max_nps": 6,
"timestamp": 1035349200,
"timestamp_format": "Oct 23 2002",
"swf_version": 1675121154
},
...
]