rounded logo SC2 Assistant | Forums
login | API | help
API
General Information

SC2Assistant offers an API to access some of our information about players, replays, strategies, statistics and more! Please use the information below to access the information you would like. Also, we ask that you link back to SC2Assistant using the embed codes, regular links or one of our images shown below.

Also, we would like to thank sc2ranks for some of our data and if you would like up to date player data about Battle.net divisions, ranks, and standings please go to sc2ranks.com!

Each of the sections below is a different page that will return information about one of the following:

  • Matchups
  • Players
  • Replays
  • Strategies
  • VODs
  • Add a Replay

Every API call require a parameter named 'key'. This should be the URL of the website you are calling the API from. We need this for statistical and informative purposes.

All requests are made using URL GET parameters and all responses come in an XML format. Some of the response data is outlined below. Also, please remember to URL encode any strings sent as GET parameters.

Matchup
URL: http://www.sc2assistant.com/api/matchup.php
Description: Returns information about one matchup between two players. It will return the win rates, some basic information and the IDs of the replays. Use the replay API to get more information on each replay.

Parameters
Name Required Description
bnet_id1 Yes The Battle.net ID of the first player you are searching for.
region_1 Yes [US, EU, SG, KR, RU, TW, LA] - The region of the first player you are looking for.
bnet_id2 Yes The Battle.net ID of the second player you are searching for.
region_2 Yes [US, EU, SG, KR, RU, TW, LA] - The region of the first player you are looking for.
Key Yes The URL of your website.


Example
Request: http://www.sc2assistant.com/api/matchup.php?bnet_id1=610382&region1=US&bnet_id2=2136786&region2=US&key=sc2assistant.com
Response:
<?xml version="1.0" encoding="ISO-8859-1"?><matchup><player1><bnet_id>610382</bnet_id><name>HforPREZ</name><region>US</region><win_rate>0.42857142857143</win_rate><races><terran>0</terran><protoss>7</protoss><zerg>0</zerg></races></player1><player2><bnet_id>2136786</bnet_id><name>Hyde</name><region>US</region><win_rate>0.57142857142857</win_rate><races><terran>0</terran><protoss>0</protoss><zerg>7</zerg></races></player2><replays><replay_id>2503</replay_id><winner_id>610382</winner_id><map>MLG Metalopolis</map><replay_id>280</replay_id><winner_id>2136786</winner_id><map>Xel'Naga Caverns</map><replay_id>279</replay_id><winner_id>2136786</winner_id><map>Xel'Naga Caverns</map><replay_id>278</replay_id><winner_id>2136786</winner_id><map>Metalopolis</map><replay_id>277</replay_id><winner_id>2136786</winner_id><map>Xel'Naga Caverns</map><replay_id>276</replay_id><winner_id>610382</winner_id><map>Xel'Naga Caverns</map><replay_id>275</replay_id><winner_id>610382</winner_id><map>Metalopolis</map></replays></matchup>
Player
URL: http://www.sc2assistant.com/api/player.php
Description: Returns information about one player based on the 6-7 digit Battle.net ID and region.

Parameters
Name Required Description
bnet_id Yes The name of the player you are searching for. It must be at least 3 characters long.
region Yes [US, EU, SG, KR, RU, TW, LA] - The region of the first player you are looking for.
Key Yes The URL of your website.


Example
Request: http://www.sc2assistant.com/api/player.php?bnet_id=388538&region=US&key=sc2assistant.com
Response:
<?xml version="1.0" encoding="ISO-8859-1"?><player><bnet_id>388538</bnet_id><region>US</region><name>LiquidHuK</name><race>Protoss</race><league></league><points></points><games_played><total>9</total><terran>0</terran><protoss>9</protoss><zerg>0</zerg></games_played><win_rates><overall>0.44444444444444</overall><vs_terran>0.66666666666667</vs_terran><vs_protoss>0</vs_protoss><vs_zerg>0.4</vs_zerg></win_rates><replays><replay_id>3173</replay_id><replay_id>3159</replay_id><replay_id>3152</replay_id><replay_id>3149</replay_id><replay_id>3107</replay_id><replay_id>3098</replay_id><replay_id>3097</replay_id><replay_id>2966</replay_id><replay_id>2965</replay_id></replays><strategies><strategy_id>8902</strategy_id><strategy_id>8894</strategy_id><strategy_id>8886</strategy_id><strategy_id>8856</strategy_id><strategy_id>8833</strategy_id><strategy_id>8753</strategy_id><strategy_id>8608</strategy_id><strategy_id>8605</strategy_id><strategy_id>8595</strategy_id></strategies></player>
Players
URL: http://www.sc2assistant.com/api/player.php
Description: Returns the IDs, Names and Regions of players that have a substring match of the search name given. More info can be received by calling the Player API with the ID of the player you would like more information about.

Parameters
Name Required Description
name Yes The name of the player you are searching for. It must be at least 3 characters long.
key Yes The URL of your website.


Example
Request: http://www.sc2assistant.com/api/players.php?name=LiquidHuk&key=sc2assistant.com
Response:
<?xml version="1.0" encoding="ISO-8859-1"?><players><player><bnet_id>524063</bnet_id><region>US</region><name>LiquidHuK</name></player><player><bnet_id>388538</bnet_id><region>US</region><name>LiquidHuK</name></player></players>
Replay
URL: http://www.sc2assistant.com/api/replay.php
Description: Returns information about one replay based on the ID.

Parameters
Name Required Description
id Yes The ID of the strategy you want information about. These IDs can be found by getting information on a player or replay.
key Yes The URL of your website.


Example
Request: http://www.sc2assistant.com/api/replay.php?id=1327&key=sc2assistant.com
Response:
<?xml version="1.0" encoding="ISO-8859-1"?><replay><id>1337</id><game_version>1.2.2.17811</game_version><map>Xel'Naga Caverns</map><game_length>591</game_length><game_speed>Faster</game_speed><realm>US</realm><date_played>1298416641</date_played><rating>0</rating><race1>Zerg</race1><race2>Zerg</race2><player1_name>Kej</player1_name><player2_name>Bluewaffle</player2_name><player1_bnet_id>437004</player1_bnet_id><player2_bnet_id>1675713</player2_bnet_id><player1_league>diamond</player1_league><player2_league>gold</player2_league><player1_points>1029</player1_points><player2_points>0</player2_points><winner_name>Bluewaffle</winner_name><winner_bnet_id>1675713</winner_bnet_id><event>BNet</event><num_downloads>3</num_downloads><strategies><player1_low_level_strategy><strategy_id>2597</strategy_id></player1_low_level_strategy><player2_low_level_strategy><strategy_id>2598</strategy_id></player2_low_level_strategy></strategies><embed_code><![CDATA[<div id='sc2assistant_link'><a href='http://www.sc2assistant.com'>SC2Assistant</a></div><script src="http://www.sc2assistant.com/javascript/embed_replay.php?id=1337" type="text/javascript"></script><script type="text/javascript">embed();</script>]]></embed_code></replay>
Strategy
URL: http://www.sc2assistant.com/api/strategy.php
Description: Returns information about one strategy based on the ID.

Parameters
Name Required Description
id Yes The ID of the strategy you want information about. These IDs can be found by getting information on a player or replay.
key Yes The URL of your website.


Example
Request: http://www.sc2assistant.com/api/strategy.php?id=1327&key=sc2assistant.com
Response:
<?xml version="1.0" encoding="ISO-8859-1"?><strategy><id>1327</id><type>low</type><name>Protoss vs Protoss</name><player>296043</player><race>Protoss</race><league>master</league><rating>0</rating><opponent_races><terran>No</terran><protoss>Yes</protoss><zerg>No</zerg></opponent_races><win_rates><overall>0</overall><vs_terran>0</vs_terran><vs_protoss>0</vs_protoss><vs_zerg>0</vs_zerg></win_rates><elements><element><supply>7/10</supply><unit>Probe</unit><time>1.75</time></element><element><supply>8/10</supply><unit>Probe</unit><time>19.125</time></element><element><supply>9/10</supply><unit>Probe</unit><time>30.1875</time></element>...<num_replays>1</num_replays><replays><replay_id>4183</replay_id></replays></strategy>
VODs
URL: http://www.sc2assistant.com/api/vods.php
Description: Returns a series of VODs with the associated information based on the search parameters. At least one of the optional parameters must be provided.

Parameters
Name Required Description
search Optional String - The name VOD. Performs a substring search.
author Optional String - The name Author of the VOD. Performs a substring search.
rating Optional Integer - Only return VODs with a rating higher than the number given.
start Optional Integer - The starting position of the results. The number of results at one time is limited to 25.
key Yes The URL of your website.


Example
Request: http://www.sc2assistant.com/api/vods.php?search=idra&key=sc2assistant.com
Response:
<?xml version="1.0" encoding="ISO-8859-1"?><vods><vod><name>wcg idra vs stage g1</name><author>HuskyStarcraft</author><rating>N/A</rating></vod><vod><name>wcg idra vs stage g2</name><author>HuskyStarcraft</author><rating>N/A</rating></vod><vod><name>wcg idra vs stage g3</name><author>HuskyStarcraft</author><rating>N/A</rating></vod><vod><name>wcg idra vs stage g4</name><author>HuskyStarcraft</author><rating>N/A</rating></vod><vod><name>IdrA vs. CrunCher g1 - StarCraft 2 Commentary (#356)</name><author>AskJoshy</author><rating>N/A</rating></vod><vod><name>IdrA vs. CrunCher g2 - StarCraft 2 Commentary (#357)</name><author>AskJoshy</author><rating>N/A</rating></vod><vod><name>IdrA vs. CrunCher g3 - StarCraft 2 Commentary (#358)</name><author>AskJoshy</author><rating>N/A</rating></vod><vod><name>#276 ZvP EGIdrA (Z) vs coLCrunCher (P) Shakuras Plateau</name><author>AdebisiStarcraft</author><rating>N/A</rating></vod><vod><name>idra cruncher g1</name><author>AdebisiStarcraft</author><rating>N/A</rating></vod>...</vods>
Add a Replay
URL: http://www.sc2assistant.com/api/add_replay.php
Description: Adds a Replay to our database so you can get statistics using our API. NOTE: replay MUST be a POST parameter rather than a GET parameter due to the size of replay files! The others can be either POST or GET parameters.

Parameters
Name Required Description
replay Yes The replay file.
event Optional Name of the event the replay was played at. Defaults to BNet.
key Yes The URL of your website.

A success parameter of either the ID of the new replay or 0 is returned. This ID can be used with the Replay API to get info about the replay that was added.