| Title: | Blizzard SC2 API Wrapper |
|---|---|
| Description: | A wrapper for Blizzard's Starcraft II (a 2010 real-time strategy game) Application Programming Interface (API). All documented API calls are implemented in an easy-to-use and consistent manner. |
| Authors: | Samuel Morrissette [cre, aut] |
| Maintainer: | Samuel Morrissette <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 1.0.0.9000 |
| Built: | 2025-02-18 03:41:01 UTC |
| Source: | https://github.com/sammorrissette/sc2api |
The Blizzard API uses OAuth 2.0 for authorization. For more information on how Blizzard uses OAuth in their API, visit https://develop.battle.net/documentation/guides/using-oauth.
Before using the Blizzard API, one must first create a client in the Blizzard Developer Portal and obtain a valid client ID and client secret. For more information on getting started, see: Getting Started.
Once a client has been created, use set_token and supply the client id and client
secret as arguments to set an environment variable for all future API calls.
Once set_token() has been used, an access token can be removed from the environment
using remove_token()
Note that access tokens are set to expire in 24 hours and, subsequently, a new token must be used for any future API calls.
set_token(client_id, client_secret, access_token, verbose = FALSE) validate_token(access_token) unset_token()set_token(client_id, client_secret, access_token, verbose = FALSE) validate_token(access_token) unset_token()
client_id, client_secret
|
A client ID and client secret can be obtained from the Blizzard Developer Portal. For more information on creating a client, visit Getting Started. |
access_token |
An OAuth 2.0 access token required to use the Blizzard API. Access tokens can be
obtained by using |
verbose |
If verbose is set to TRUE, your access token will be printed on screen. |
Access tokens expire after 24 hours.
## Not run: #Get and set a token as an environment variable set_token(client_id = "YOUR CLIENT ID", client_secret = "YOUR CLIENT SECRET") #Set an access token that you have already retrieved as an environment variable set_token(access_token = "YOUR TOKEN") ## End(Not run) # Ensure that a valid token is currently set as an environment variable validate_token() # Check if a token is valid validate_token("TEST TOKEN") # Remove token from environment variable unset_token()## Not run: #Get and set a token as an environment variable set_token(client_id = "YOUR CLIENT ID", client_secret = "YOUR CLIENT SECRET") #Set an access token that you have already retrieved as an environment variable set_token(access_token = "YOUR TOKEN") ## End(Not run) # Ensure that a valid token is currently set as an environment variable validate_token() # Check if a token is valid validate_token("TEST TOKEN") # Remove token from environment variable unset_token()
Provides a full listing of players currently in the grandmaster leaderboard. Also provides other information such as player profile information, records (match record, MMR, etc.), and clans.
get_gm_leaderboard(region_id, host_region = "us")get_gm_leaderboard(region_id, host_region = "us")
region_id |
A numeric argument indicating the region of the profile.
|
host_region |
The host region that the API call will be sent to. For most API calls, the same data will be returned regardless of which region the request is sent to. Must be one of "us", "eu", "kr", "tw", "cn". For more information on regionality, refer to Regionality and APIs. |
This API call is currently not supported for the China region (region_id = 5).
Other ladder data API calls:
get_season()
# Obtain GM leaderboard for the Korea region try(get_gm_leaderboard(region_id = 3))# Obtain GM leaderboard for the Korea region try(get_gm_leaderboard(region_id = 3))
Provides information about a particular ladder and the individual's rank and status within that ladder (i.e. rank, MMR, etc.).
get_ladder(region_id, realm_id, profile_id, ladder_id, host_region = "us")get_ladder(region_id, realm_id, profile_id, ladder_id, host_region = "us")
region_id |
A numeric argument indicating the region of the profile.
|
realm_id |
A numeric argument indicating the realm of the profile. A realm is a subset of the region.
|
profile_id |
A unique, numeric identifier for an individual's profile. |
ladder_id |
A unique identifier for a particular ladder. With the exception of Grandmaster, leagues (bronze, silver, etc.), are separated into tiers (1,2,3) which are further separated into divisions. These divisions, or ladders, each have a unique identifier. |
host_region |
The host region that the API call will be sent to. For most API calls, the same data will be returned regardless of which region the request is sent to. Must be one of "us", "eu", "kr", "tw", "cn". For more information on regionality, refer to Regionality and APIs. |
Other profile API calls:
get_ladder_summary(),
get_metadata(),
get_profile(),
get_static()
# Obtaining the overall ladder performance of a profile. try({ ladderData <- get_ladder_summary(region_id = 1, realm_id = 1, profile_id = 4716773) # Choose a single ladder ID ladderID <- ladderData$allLadderMemberships$ladderId[1] # Get full ladder information and the profile's performance in this ladder get_ladder(region_id = 1, realm_id = 1, profile_id = 4716773, ladder_id = ladderID) })# Obtaining the overall ladder performance of a profile. try({ ladderData <- get_ladder_summary(region_id = 1, realm_id = 1, profile_id = 4716773) # Choose a single ladder ID ladderID <- ladderData$allLadderMemberships$ladderId[1] # Get full ladder information and the profile's performance in this ladder get_ladder(region_id = 1, realm_id = 1, profile_id = 4716773, ladder_id = ladderID) })
Provides data of players in a particular ladder. This includes MMR, points, win/loss record, time of joining, time of a player's last game, and more.
get_ladder_data(ladder_id, host_region = "us")get_ladder_data(ladder_id, host_region = "us")
ladder_id |
A unique identifier for a particular ladder. With the exception of grandmaster, leagues (bronze, silver, etc.), are separated into tiers (1,2,3) which are further separated into divisions. These divisions, or ladders, each have a unique identifier. |
host_region |
The host region that the API call will be sent to. For |
For get_ladder_data, the host region MUST be the region that the ladder is a part of.
Other game data API calls:
get_league_data(),
get_season_data()
### Obtain battle tags and MMR of players in a particular ladder. #Get full ladder data try({ data <- get_ladder_data(ladder_id = 289444, host_region = "us") # Player ratings ratings <- data$team$rating # Get battle tags using list indexing with sapply tags <- sapply(data$team$member, function(x) x$character_link$battle_tag) })### Obtain battle tags and MMR of players in a particular ladder. #Get full ladder data try({ data <- get_ladder_data(ladder_id = 289444, host_region = "us") # Player ratings ratings <- data$team$rating # Get battle tags using list indexing with sapply tags <- sapply(data$team$member, function(x) x$character_link$battle_tag) })
Provides ladder ID's for all divisions in a league's tiers.
get_ladder_ids(season_id, queue_id, team_type, league_id, host_region)get_ladder_ids(season_id, queue_id, team_type, league_id, host_region)
season_id |
A numeric argument indicating a particular ladder season. Currently, league data is only available for season 28 and higher (i.e. data prior to this season is inaccessible). |
queue_id |
|
team_type |
|
league_id |
|
host_region |
The host region that the API call will be sent to. For |
List of ladder ID's separated by tier. For grandmaster league, an integer is returned.
Data is only available for season 28 and higher.
# Get all ladder ID's for Season 35, LotV 2v2, randomly gathered teams, # Bronze league, Korean region. try({ data <- get_ladder_ids(season_id = 35, queue_id = 202, team_type = 1, league_id = 0, host_region = "kr") })# Get all ladder ID's for Season 35, LotV 2v2, randomly gathered teams, # Bronze league, Korean region. try({ data <- get_ladder_ids(season_id = 35, queue_id = 202, team_type = 1, league_id = 0, host_region = "kr") })
Provides a detailed list of ladder membership, profile showcases, and placement matches.
get_ladder_summary(region_id, realm_id, profile_id, host_region = "us")get_ladder_summary(region_id, realm_id, profile_id, host_region = "us")
region_id |
A numeric argument indicating the region of the profile.
|
realm_id |
A numeric argument indicating the realm of the profile. A realm is a subset of the region.
|
profile_id |
A unique, numeric identifier for an individual's profile. |
host_region |
The host region that the API call will be sent to. For most API calls, the same data will be returned regardless of which region the request is sent to. Must be one of "us", "eu", "kr", "tw", "cn". For more information on regionality, refer to Regionality and APIs. |
Other profile API calls:
get_ladder(),
get_metadata(),
get_profile(),
get_static()
# Request ladder summary of a particular profile in the U.S. region and U.S. realm. try(get_ladder_summary(region_id = 1, realm_id = 1, profile_id = 4716773))# Request ladder summary of a particular profile in the U.S. region and U.S. realm. try(get_ladder_summary(region_id = 1, realm_id = 1, profile_id = 4716773))
Get the time of the last played match in a player's match history.
get_last_played(region_id, realm_id, profile_id, host_region = "us")get_last_played(region_id, realm_id, profile_id, host_region = "us")
region_id |
A numeric argument indicating the region of the profile.
|
realm_id |
A numeric argument indicating the realm of the profile. A realm is a subset of the region.
|
profile_id |
A unique, numeric identifier for an individual's profile. |
host_region |
The host region that the API call will be sent to. For most API calls, the same data will be returned regardless of which region the request is sent to. Must be one of "us", "eu", "kr", "tw", "cn". For more information on regionality, refer to Regionality and APIs. |
Data is only available for season 28 and higher.
# Get last played match for a particular profile try(get_last_played(1, 4716773, host_region = "us"))# Get last played match for a particular profile try(get_last_played(1, 4716773, host_region = "us"))
Provides both league (i.e. bronze, silver, etc.) and tier (1, 2, 3) player counts.
get_league_counts(season_id, queue_id, team_type, league_id, host_region)get_league_counts(season_id, queue_id, team_type, league_id, host_region)
season_id |
A numeric argument indicating a particular ladder season. Currently, league data is only available for season 28 and higher (i.e. data prior to this season is inaccessible). |
queue_id |
|
team_type |
|
league_id |
|
host_region |
The host region that the API call will be sent to. For |
A list with tier counts and the overall league count.
Data is only available for season 28 and higher.
# Get league counts for Season 35, LotV 2v2, randomly gathered teams, # Bronze league, Korean region. try({ data <- get_league_counts(season_id = 35, queue_id = 202, team_type = 1, league_id = 0, host_region = "kr") })# Get league counts for Season 35, LotV 2v2, randomly gathered teams, # Bronze league, Korean region. try({ data <- get_league_counts(season_id = 35, queue_id = 202, team_type = 1, league_id = 0, host_region = "kr") })
League data is divided into 3 tiers for each league (with the exception of grandmaster, which only has 1 tier) and further divided into a number of divisions depending on how many players are in a given league. League data contains the number of divisions, the unique ladder ID of each division and the total player count contained within each division.
get_league_data(season_id, queue_id, team_type, league_id, host_region = "us")get_league_data(season_id, queue_id, team_type, league_id, host_region = "us")
season_id |
A numeric argument indicating a particular ladder season. Currently, league data is only available for season 28 and higher (i.e. data prior to this season is inaccessible). |
queue_id |
|
team_type |
|
league_id |
|
host_region |
The host region that the API call will be sent to. For |
League data is only available for season 28 and higher.
Other game data API calls:
get_ladder_data(),
get_season_data()
# Get full league data for Season 30, LotV 1v1, arranged teams, # Masters league, U.S. region. try({ data <- get_league_data(season_id = 30, queue_id = 201, team_type = 0, league_id = 5, host_region = "us") })# Get full league data for Season 30, LotV 1v1, arranged teams, # Masters league, U.S. region. try({ data <- get_league_data(season_id = 30, queue_id = 201, team_type = 0, league_id = 5, host_region = "us") })
Provides a listing of available achievements in Starcraft II.
get_legacy_achievements(region_id, host_region = "us")get_legacy_achievements(region_id, host_region = "us")
region_id |
A numeric argument indicating the region of the profile.
|
host_region |
The host region that the API call will be sent to. For most API calls, the same data will be returned regardless of which region the request is sent to. Must be one of "us", "eu", "kr", "tw", "cn". For more information on regionality, refer to Regionality and APIs. |
Legacy API call. It is recommended to use get_static instead.
Other legacy API calls:
get_legacy_ladders(),
get_legacy_ladder(),
get_legacy_match_history(),
get_legacy_profile(),
get_legacy_rewards()
Provides a listing of players in a given ladder. Also provides other information such as their ladder record, points, profile information, and clan.
get_legacy_ladder(region_id, ladder_id, host_region = "us")get_legacy_ladder(region_id, ladder_id, host_region = "us")
region_id |
A numeric argument indicating the region of the profile.
|
ladder_id |
A unique identifier for a particular ladder. With the exception of Grandmaster, leagues (bronze, silver, etc.), are separated into tiers (1,2,3) which are further separated into divisions. These divisions, or ladders, each have a unique identifier. |
host_region |
The host region that the API call will be sent to. For most API calls, the same data will be returned regardless of which region the request is sent to. Must be one of "us", "eu", "kr", "tw", "cn". For more information on regionality, refer to Regionality and APIs. |
Legacy API call. It is recommended to use get_ladder_data instead.
Other legacy API calls:
get_legacy_achievements(),
get_legacy_ladders(),
get_legacy_match_history(),
get_legacy_profile(),
get_legacy_rewards()
Provides information about a profile's performance in the current season, previous season, and showcase entries.
get_legacy_ladders(region_id, realm_id, profile_id, host_region = "us")get_legacy_ladders(region_id, realm_id, profile_id, host_region = "us")
region_id |
A numeric argument indicating the region of the profile.
|
realm_id |
A numeric argument indicating the realm of the profile. A realm is a subset of the region.
|
profile_id |
A unique, numeric identifier for an individual's profile. |
host_region |
The host region that the API call will be sent to. For most API calls, the same data will be returned regardless of which region the request is sent to. Must be one of "us", "eu", "kr", "tw", "cn". For more information on regionality, refer to Regionality and APIs. |
Legacy API call. For similar information, use get_ladder_summary.
Other legacy API calls:
get_legacy_achievements(),
get_legacy_ladder(),
get_legacy_match_history(),
get_legacy_profile(),
get_legacy_rewards()
Provides information about a profile's recent match history (last 25 matches, win/loss, timestamp, etc.).
get_legacy_match_history(region_id, realm_id, profile_id, host_region = "us")get_legacy_match_history(region_id, realm_id, profile_id, host_region = "us")
region_id |
A numeric argument indicating the region of the profile.
|
realm_id |
A numeric argument indicating the realm of the profile. A realm is a subset of the region.
|
profile_id |
A unique, numeric identifier for an individual's profile. |
host_region |
The host region that the API call will be sent to. For most API calls, the same data will be returned regardless of which region the request is sent to. Must be one of "us", "eu", "kr", "tw", "cn". For more information on regionality, refer to Regionality and APIs. |
Although this is a legacy API call, there is no other call available to obtain a profile's match history.
Other legacy API calls:
get_legacy_achievements(),
get_legacy_ladders(),
get_legacy_ladder(),
get_legacy_profile(),
get_legacy_rewards()
# Obtain recent 1v1 results for a profile in the U.S. region try({ matches <- get_legacy_match_history(region_id = 1, realm_id = 1, profile_id = 4716773) matches[matches$type=='1v1',"decision"] })# Obtain recent 1v1 results for a profile in the U.S. region try({ matches <- get_legacy_match_history(region_id = 1, realm_id = 1, profile_id = 4716773) matches[matches$type=='1v1',"decision"] })
Provides summary data for an individual's profile such as campaign completion, career ladder finishes, earned achievements, and much more.
get_legacy_profile(region_id, realm_id, profile_id, host_region = "us")get_legacy_profile(region_id, realm_id, profile_id, host_region = "us")
region_id |
A numeric argument indicating the region of the profile.
|
realm_id |
A numeric argument indicating the realm of the profile. A realm is a subset of the region.
|
profile_id |
A unique, numeric identifier for an individual's profile. |
host_region |
The host region that the API call will be sent to. For most API calls, the same data will be returned regardless of which region the request is sent to. Must be one of "us", "eu", "kr", "tw", "cn". For more information on regionality, refer to Regionality and APIs. |
Legacy API call. It is recommended to use get_profile instead.
Other legacy API calls:
get_legacy_achievements(),
get_legacy_ladders(),
get_legacy_ladder(),
get_legacy_match_history(),
get_legacy_rewards()
Provides a listing of available rewards in Starcraft II.
get_legacy_rewards(region_id, host_region = "us")get_legacy_rewards(region_id, host_region = "us")
region_id |
A numeric argument indicating the region of the profile.
|
host_region |
The host region that the API call will be sent to. For most API calls, the same data will be returned regardless of which region the request is sent to. Must be one of "us", "eu", "kr", "tw", "cn". For more information on regionality, refer to Regionality and APIs. |
Legacy API call. It is recommended to use get_static instead.
Other legacy API calls:
get_legacy_achievements(),
get_legacy_ladders(),
get_legacy_ladder(),
get_legacy_match_history(),
get_legacy_profile()
Provides metadata for an individual's profile including their display name, profile URL, and avatar URL.
get_metadata(region_id, realm_id, profile_id, host_region = "us")get_metadata(region_id, realm_id, profile_id, host_region = "us")
region_id |
A numeric argument indicating the region of the profile.
|
realm_id |
A numeric argument indicating the realm of the profile. A realm is a subset of the region.
|
profile_id |
A unique, numeric identifier for an individual's profile. |
host_region |
The host region that the API call will be sent to. For most API calls, the same data will be returned regardless of which region the request is sent to. Must be one of "us", "eu", "kr", "tw", "cn". For more information on regionality, refer to Regionality and APIs. |
Other profile API calls:
get_ladder_summary(),
get_ladder(),
get_profile(),
get_static()
# Request profile metadata of a particular profile in the European region and # European realm. try(get_metadata(region_id = 2, realm_id = 1, host_region = 3437681))# Request profile metadata of a particular profile in the European region and # European realm. try(get_metadata(region_id = 2, realm_id = 1, host_region = 3437681))
Provides metadata for an individual's account including a list of profiles associated with the account, as well as their their respective display names, profile URLs and avatar URLs.
get_player(account_id, host_region = "us")get_player(account_id, host_region = "us")
account_id |
A unique identifier for an individual's account. |
host_region |
The host region that the API call will be sent to. For most API calls, the same data will be returned regardless of which region the request is sent to. Must be one of "us", "eu", "kr", "tw", "cn". For more information on regionality, refer to Regionality and APIs. |
Provides summary data for an individual's profile such as campaign completion, career ladder finishes, earned achievements, and more.
get_profile(region_id, realm_id, profile_id, host_region = "us")get_profile(region_id, realm_id, profile_id, host_region = "us")
region_id |
A numeric argument indicating the region of the profile.
|
realm_id |
A numeric argument indicating the realm of the profile. A realm is a subset of the region.
|
profile_id |
A unique, numeric identifier for an individual's profile. |
host_region |
The host region that the API call will be sent to. For most API calls, the same data will be returned regardless of which region the request is sent to. Must be one of "us", "eu", "kr", "tw", "cn". For more information on regionality, refer to Regionality and APIs. |
Other profile API calls:
get_ladder_summary(),
get_ladder(),
get_metadata(),
get_static()
# Request profile summary of a particular profile in the U.S. region and U.S. realm. try(get_profile(region_id = 1, realm_id = 1, profile_id = 4716773))# Request profile summary of a particular profile in the U.S. region and U.S. realm. try(get_profile(region_id = 1, realm_id = 1, profile_id = 4716773))
Provides the current season ID, starting date, and ending date.
get_season(region_id, host_region = "us")get_season(region_id, host_region = "us")
region_id |
A numeric argument indicating the region of the profile.
|
host_region |
The host region that the API call will be sent to. For most API calls, the same data will be returned regardless of which region the request is sent to. Must be one of "us", "eu", "kr", "tw", "cn". For more information on regionality, refer to Regionality and APIs. |
Other ladder data API calls:
get_gm_leaderboard()
# Obtain current season information for the European region try(get_season(region_id = 2))# Obtain current season information for the European region try(get_season(region_id = 2))
Provides start and ending times for a given season.
get_season_data(season_id, host_region = "us")get_season_data(season_id, host_region = "us")
season_id |
A numeric argument indicating a particular ladder season. Currently, league data is only available for season 28 and higher (i.e. data prior to this season is inaccessible). |
host_region |
The host region that the API call will be sent to. For |
Season data is only available for season 28 and higher.
Other game data API calls:
get_ladder_data(),
get_league_data()
# Get season start and end times for season 35 in the European region. try({ data <- get_season_data(season_id = 35, host_region = "eu") as.POSIXct(data$start_timestamp, origin = "1970-01-01") as.POSIXct(data$end_timestamp, origin = "1970-01-01") })# Get season start and end times for season 35 in the European region. try({ data <- get_season_data(season_id = 35, host_region = "eu") as.POSIXct(data$start_timestamp, origin = "1970-01-01") as.POSIXct(data$end_timestamp, origin = "1970-01-01") })
Provides static information (achievements, categories, criteria, and rewards) about SC2 profiles in a given region.
get_static(region_id, host_region = "us")get_static(region_id, host_region = "us")
region_id |
A numeric argument indicating the region of the profile.
|
host_region |
The host region that the API call will be sent to. For most API calls, the same data will be returned regardless of which region the request is sent to. Must be one of "us", "eu", "kr", "tw", "cn". For more information on regionality, refer to Regionality and APIs. |
Other profile API calls:
get_ladder_summary(),
get_ladder(),
get_metadata(),
get_profile()
# Request static data of profiles in the EU region. Request is sent through # the U.S. host region. try(get_static(region_id = 2, host_region = "us")) # Request static data of profiles in the China region. The request must be # sent to the China gateway. try(get_static(region_id = 5, host_region = "cn"))# Request static data of profiles in the EU region. Request is sent through # the U.S. host region. try(get_static(region_id = 2, host_region = "us")) # Request static data of profiles in the China region. The request must be # sent to the China gateway. try(get_static(region_id = 5, host_region = "cn"))
SC2API packageA simple wrapper written in R for Blizzard's Starcraft II API. Enables users to retrieve various data pertaining to accounts, profiles, seasons and ladders.
Before using, it is recommended to view the README on GitHub
Further documentation can be found in Blizzard's Starcraft II API documentation.