APIs are provided to make getting data out of SC2Ranks easier. While not everything will be exposed, you are welcome to email shadow@sc2ranks.com if you have a request.
Characters can either be found by passing "name!battle.net id" to use the battle.net id you see on your battle.net profile, or through "name$character code" to use the character code.
Characters that aren't in the database yet will be queued if a battle.net id is passed. Character codes will not auto queue as you cannot go from character code -> battle.net profile. You should avoid using character codes when possible.
Valid regions are: am, eu, fae, sea, cn
All APIs support XML or JSON data, append ".json" or ".xml" to change the format returned. For JSONP pass "?jsonp=foobar" to get a function call for 'foobar' wrapped around the JSON data. Requests also have ETags attached to them, you reduce the data parsing necessary if you use ETags and don't reparse if you see 304 Not Modified.
You must link back to SC2 Rank profiles, or to sc2ranks.com depending on how you are using data.
You cannot use the data in mobile applications (websites with mobile HTML versions not included), without permission. We're not looking at adding new mobile apps for iOS or Android at this time.
Cache your requests, you should not be pulling from SC2Ranks every time someone visits a page with the data.
Blizzard does not provide character codes on battle.net anymore, while some characters will still work with a character code, you should not rely on it. You can do more specific character searching by division, team points and so on with the "Profile Search" API below.
Application keys are required for all API requests, if you do not pass "?appKey=example.com" you will get a no_key error. These are used for statistics on requests.
Keys are not given out, just use the domain you are showing the data on. If you are requesting it for "foobar.com" then it would be "?appKey=foobar.com"
Some awesome users have made tools to make using SC2 Ranks data easier. If you made something I missed, let me know and I'll get it added.
Python - http://github.com/canute/sc2ranks by Canute
.NET 4.0 - http://sc2ranksnet.codeplex.com/ by Kralizek
Ruby - http://github.com/Soleone/sc2ranks by Soleone
PHP - http://github.com/ameerkat/sc2ranks-php by ameerkat
Drupal plugin - http://github.com/ameerkat/sc2ranks-drupal by ameerkat
C++ - http://code.google.com/p/sc2ranks-cpp-lib/ by Vevix
There are a few ways to link to pages on SC2 Ranks using different data you get back from the API.
Character profiles with battle.net id: http://sc2ranks.com/char/[region]/[bnet id]/[name]
Character profiles with character code: http://sc2ranks.com/charcode/[region]/[code]/[name]
Division with internal id: http://sc2ranks.com/div/[sc2rank id]
Divisions with battle.net id: http://sc2ranks.com/div/bnet/[bnet id]
Let's you search for profiles to find a characters battle.net id, an exact duplicate of the "Profile Finder" tab. Replacement to allow you to search for characters without having the character code, or relying purely on names.
type can be 1t, 2t, 3t, 4t, achieve. #t refers to team, so 1t is 1v1 team and so on, achieve refers to the characters achievements.
sub_type can be points, wins, losses, division for #t, otherwise it's just points.
value is the value of what to search on based on type + sub_type, if you passed division then it's the division name, if you pass losses it's the total number of losses and so on. Matches are all inexact, if you pass 500 for points it searches for >= 400 and <= 600, if you search for division name it does an inexact match.
URL format: http://sc2ranks.com/api/psearch/[region]/[name]/[type]/[sub_type]/[value]
Example: http://sc2ranks.com/api/psearch/am/Shadowed/1t/division/DuGalle
Error: no_character if none are found.
Cached: 30 minutes
Minimum amount of character data, just gives achievement points, character code and battle.net id info.
URL format: http://sc2ranks.com/api/base/char/[region]/[name]
Example: http://sc2ranks.com/api/base/char/am/HuK$530
Error: no_character if a character does not exist
Cached: 1 hour
Portraits are available in 45x45, 75x75 and 90x90.
If portraits have been loaded, you will see a key with "portrait" containing data to get the players current portrait. icon_id refers to the sprite image series, 2 would refer to "portraits-2-##.jpg".
column and row are used to find the location of the sprite, For example column 3, row 1, icon id 2 would translate into the Sarah Kerrigan portrait at 75x75 by doing -(3 * 75) = -225 and -(1 * 75) = -75 to find the location. Which would give you the following CSS code (replace /images/ with the path to the image):
background: url('/images/achievements-2-75.jpg') -225px -75px no-repeat; width: 75px; height: 75px;
Includes base character data, as well as base data on all of the players teams. If you need team members you need the API below.
URL format: http://sc2ranks.com/api/base/teams/[region]/[name]
Example: http://sc2ranks.com/api/base/teams/am/HuK$530
Error: no_character if a character does not exist
Cached: 3 hours
Includes base character data, and extended team information for the passed bracket.
URL format: http://sc2ranks.com/api/char/teams/[region]/[name]/[bracket]/[0 or 1 is random]
URL format with rankings: http://sc2ranks.com/api/char/teams/[region]/[name]/[bracket]/[0 or 1 is random]
Example: http://sc2ranks.com/api/char/teams/am/HuK$530/1/0
Error: no_character if a character does not exist.
Cached: 6 hours
Same as pulling just character information, except you can pull 100 characters at once. The returns are the same, except you get an array of characters rather than a hash. Since a lot more data can be returned, only JSON is available, you cannot get XML from the API due to XML being rather verbose. Names have to be passed through POST requests rather than URLs as well.
AJAX request in Javascript for example: {"characters":[{"bnet_id":388538,"region":"us","name":"HuK"},{"region":"us","name":"dayvie","code":947}]}
Raw post request of the above: characters[0][region]=us&characters[0][name]=HuK&characters[0][bnet_id]=388538&characters[1][region]=us&characters[1][name]=dayvie&characters[1][code]=947
URL format: http://sc2ranks.com/api/mass/base/char/
Error: no_characters if you do not pass any characters or too_many_characters if you pass over 100 characters to be returned at once.
Cached: 1 hour
Works the same as pulling base team information for a character, except you can pull 100 characters at once. The returns are the same, except you get an array of characters rather than a hash. Since a lot more data can be returned, only JSON is available, you cannot get XML from the API due to XML being rather verbose. Names have to be passed through POST requests rather than URLs as well.
Bracket is the bracket you want the players teams from, bracket => 1, is_random => 0 gets you 1v1, if you want 4v4 random you would do bracket => 4, is_random => 1
AJAX request in Javascript for example: {"team":{"is_random":0,"bracket":1},"characters":[{"bnet_id":388538,"region":"us","name":"HuK"},{"region":"us","name":"dayvie","code":947}]}
Raw post request of the above: team[bracket]=1&team[is_random]=0&characters[0][region]=us&characters[0][name]=HuK&characters[0][bnet_id]=388538&characters[1][region]=us&characters[1][name]=dayvie&characters[1][code]=947
URL format: http://sc2ranks.com/api/mass/base/teams/
Error: no_characters if you do not pass any characters or too_many_characters if you pass over 100 characters to be returned at once.
Cached: 3 hours
Allows you to perform small searches, useful if you want to hookup an IRC bot or such. Only returns the first 10 names, but you can see the total number of characters and pass an offset if you need more. Search is case-insensitive.
Search type can be exact, contains, starts, ends.
URL format: http://sc2ranks.com/api/search/[search type]/[region]/[name]
URL format with offsets: http://sc2ranks.com/api/search/[search type]/[region]/[name]/[offset]
Example: http://sc2ranks.com/api/exact/search/am/shadow
Errors: no_characters no characters found.
Cached: 30 minutes
Allows you to get everyone in a custom division.
URL format: http://sc2ranks.com/api/clist/[div id]/[region or all]/[league or all]/[bracket]/[1 or 0 for random brackets]
Example: http://sc2ranks.com/api/clist/1/all/all/1/0
Errors: no_characters no characters added to division yet, no_custom no custom division by that id.
Cached: 12 hours
Allows you to add or remove characters to a custom division, to reduce abuse you are required to use the custom divisions password to manage.
URL format: http://sc2ranks.com/api/custom/[custom id]/[password]/[add or remove]/[comma separated characters]
Example: http://sc2ranks.com/api/custom/1/testing/remove/AM-Shadowed!738095,AM-dayvie!715900,AM-qxc!689672.json
The number is the battle.net id found in battle.net or sc2rank.com profile links. For example: http://sc2ranks.com/am/738095/Shadowed becomes "AM-Shadowed!738095"
Errors: bad_type type argument was not add or remove, failed_auth password incorrect, no_custom no custom division found, banned ip banned.
You will get a list of characters with the status of adding them. Added/removed/queued status will be passed regardless of the character already having been added or removed. Example formats:
Successful add/remove: {:status => [queued/added/removed], :char => [list of characters from url]}
Error in parsing: {:error => [bad_format], :char => [list of character from url]
Returns the total bonus pool for every region, regions are typically within 10 points of each other.
URL: http://sc2ranks.com/api/bonus/pool
