Counter-Strike: Global Offensive PickEm Fantasy Management

From Valve Developer Community
Jump to: navigation, search
This page outlines the basics of creating a website or application to help players manage their predictions in CS:GO Pick'Em Challenges or CS:GO Fantasy games. It also introduces Game Authentication Codes provided for CS:GO Major Championships.
Counter-Strike: Global Offensive

By default CS:GO Pick'Em Challenge and Fatasy games can only be played by running the CS:GO desktop client. Game Authentication Codes allow third-party websites and applications to access users Pick'Em Challenge predictions and Fantasy game lineups, and help users place tournament team stickers and tournament player autographs that users own as predictions and fantasy roster picks during CS:GO Major Championships.

When users use their tournament sticker to make Pick'Em predictions, that sticker will be locked until the end of the match day. When users use their player autograph for fantasy roster pick, that sticker will be locked until the end of the tournament. Locked stickers are unusable and untradable until the lock expires. Removing predictions at a later time will not undo the lock.

Creating Game Authentication Code

Users can create their game authentication codes using Steam help site, and then share their authentication code with third-party website or application.

https://help.steampowered.com/en/wizard/HelpWithGameIssue/?appid=730&issueid=128

Steam Support doesn't review or endorse third-party websites or applications that request access to Game Authentication Codes, and can take no responsibility for those websites or applications. If users don't trust the website or application that is requesting information, users should not approve the request.

Users can always revoke previously issued authentication codes.

Creating Steam Web API Key

Website or application developer is responsible for creating their Steam Web API key.

https://steamcommunity.com/dev/apikey

Website or application developer must comply with Steam Web API Terms of Use.

https://steamcommunity.com/dev/apiterms

When website or application developer are eligible to use a privileged partner Web API access endpoint, they should do so. Otherwise this document will assume Steam Web API access via https://api.steampowered.com/. Examples provided in this document will use event=9 to refer to 2016 MLG Columbus Major CS:GO Championship.

Tournament Layout

Tournament layout can be accessed using the following HTTP GET request:

https://api.steampowered.com/ICSGOTournaments_730/GetTournamentLayout/v1?key=XXX&event=9

Each event consists of multiple days identified with the corresponding sectionid.

Each day consists of multiple matchups referred to as groups identified with the corresponding groupid.

Each matchup has a number of points to award per correct prediction pick and whether picks are still allowed for that matchup.

Each matchup is between two teams identified by their corresponding pickid. If the outcome of the matchup is known then the winning team will be included under picks array of pickids.

If multiple picks are possible for the group (events prior to MLG Columbus 2016 Major Championship), then picks array will contain multiple blocks, each with an incrementing index field. Within each pick for a given index an array of pickids is provided when known. User should be scored the designed number of points per pick if their pick for a given index can be found in the array of pickids for that index.

User Predictions

User predictions can be access using the following HTTP GET request:

https://api.steampowered.com/ICSGOTournaments_730/GetTournamentPredictions/v1?key=XXX&event=9&steamid=765XXX&steamidkey=AAAA-AAAAA-AAAA

User's steamid and correct user's authentication code must be supplied.

Predictions are returned as an array containing groupid and pick for each prediction made by the user.

User Fantasy Lineups

User fantasy lineups can be accessed using the following HTTP GET request:

https://api.steampowered.com/ICSGOTournaments_730/GetTournamentFantasyLineup/v1?key=XXX&event=9&steamid=765XXX&steamidkey=AAAA-AAAAA-AAAA

User's steamid and correct user's authentication code must be supplied.

Fantasy lineups are returned as an array containing sectionid for the day when user lineup becomes active, and an array of picks containing schema ids of professional players in the corresponding slots on their fantasy roster. All five players will always be present on the roster lineup because clients cannot submit incomplete rosters.

Users don't have to change a fantasy roster lineup for every tournament day. If user didn't customize their fantasy roster lineup for one of the tournament days then the website or application developer must treat user's fantasy roster lineup from the most recent previous day as active on that tournament day and calculate points earned accordingly.

Schema ids of professional players can be found in "pro_players" section of items_game.txt file shipped with CS:GO client.

Example response:

{
	"result": {
		"teams": [
			{
				"sectionid": 23,
				"picks": [
					156257548,
					3648428,
					108076825,
					12065295,
					424467
				]
				
			},
			{
				"sectionid": 24,
				"picks": [
					71385856,
					31082355,
					108076825,
					28361465,
					71288472
				]
				
			},
			{
				"sectionid": 28,
				"picks": [
					23429534,
					79720871,
					170178574,
					38921219,
					424467
				]
				
			}
		]
		
	}
}

This response indicates that user didn't have a fantasy lineup until tournament day sectionid=23, user updated their fantasy lineup for tournament day sectionid=24, then user kept the same exact lineup throughout the following tournament days and was awarded fantasy points for that fantasy lineup on all those tournament days, and finally user made one last fantasy lineup change for tournament day sectionid=28.

User Stickers Acting as Game Pieces

User stickers acting as game pieces for Pick'Em Challenge and Fantasy Game can be accessed using the following HTTP GET request:

https://api.steampowered.com/ICSGOTournaments_730/GetTournamentItems/v1?key=XXX&event=9&steamid=765XXX&steamidkey=AAAA-AAAAA-AAAA

User's steamid and correct user's authentication code must be supplied.

The array of items owned by the user is returned. Each item is identified by its type to let website or application developer know whether it can be used for team pick (type=team), or for placing a player on fantasy roster lineup (type=player). Items returned will include no more than one item per each team pick, and no more than one item per player pick.

Team predictions must be placed using their teamid numeric value and the itemid. Players must be placed on fantasy roster using their playerid numeric value and the itemid.

Placing Pick'Em Challenge Prediction

Prediction can be placed using the following HTTP POST request:

https://api.steampowered.com/ICSGOTournaments_730/UploadTournamentPredictions/v1?key=XXX

POST body data:
event=9&steamid=765XXX&steamidkey=AAAA-AAAAA-AAAA&sectionid=15&groupid=29&index=0&pickid=57&itemid=429500386

User's steamid and correct user's authentication code must be supplied.

Because placing the prediction will lock user's sticker item, best practice for the website or application will be to obtain the confirmation from the user before placing the prediction.

Example confirmation text before placing the prediction may be:

Making a pick will lock this sticker. It will be unusable and untradable until the end of the match day. Removing this pick at a later time will not undo the lock.

If prediction is successfully placed then HTTP 200 OK will be returned and response payload will contain result JSON including itemid assigned to the locked sticker item for this pick. When different from the original itemid, the website or application must continue using only the newly returned itemid instead.

As soon as the match starts, predictions for that match can no longer be placed or changed, and HTTP 410 Gone status code will be returned.

Status code HTTP 412 Precondition Failed can be returned when placing a prediction for a particular matchup is not allowed because previously placed upstream predictions are inconsistent with the new value, or when placing or clearing a prediction for a particular matchup is not allowed because previously placed downstream predictions depend on the prediction for that matchup. The website or application should stop attempting those uploads until user gets a chance to modify previously placed predictions to satisfy the preconditions for the matchup.

If user wants to make a prediction for a team that they don't have a sticker for, then website or application may direct the user to purchase a sticker from Steam Community Market using the following URL containing the ID of the desired team:

http://steamcommunity.com/market/search?q=&category_730_TournamentTeam%5B%5D=tag_Team57&category_730_StickerCategory%5B%5D=tag_TeamLogo&category_730_Tournament%5B%5D=tag_Tournament9&appid=730

Example response:

{
        "result": {
                "itemid": 4295003884
        }
}

This response demonstrates that user's item with itemid=429500386 should no longer be used and a new item with itemid=4295003884 should be used instead.

Uploading Fantasy Lineup

Fantasy lineup can be uploaded using the following HTTP POST request:

https://api.steampowered.com/ICSGOTournaments_730/UploadTournamentFantasyLineup/v1?key=XXX

POST body data:
event=9&steamid=765XXX&steamidkey=AAAA-AAAAA-AAAA&sectionid=N&pickid0=30305781&itemid0=4295003892&pickid1=64640068&itemid1=4295003893&pickid2=7223652&itemid2=4295003894&pickid3=18216247&itemid3=4295003895&pickid4=38738282&itemid4=4295003888

User's steamid and correct user's authentication code must be supplied.

Schema IDs of professional players and corresponding IDs of sticker items owned by the user must be supplied to match the positions in which professional players should appear on the fantasy roster lineup. All five professional players must be submitted for the roster lineup at the time of this call, and no duplicate entries are allowed.

Because uploading the fantasy lineup will lock user's sticker items, best practice for the website or application will be to obtain the confirmation from the user before uploading.

Example confirmation text may be:

Submitting this roster will lock these five stickers. They will be unusable and untradable until the end of the tournament. Updating this roster at a later time will not undo the lock.

If fantasy lineup is successfully uploaded then HTTP 200 OK will be returned and response payload will contain result JSON including itemid0,itemid1,itemid2,itemid3,itemid4 assigned to the locked sticker items for this pick. When different from the original itemidN, the website or application must continue using only the newly returned itemidN instead.

As soon as the first match of the tournament day section starts, fantasy lineups for that tournament day section can no longer be uploaded or changed, and HTTP 410 Gone status code will be returned.

If fantasy lineups for the tournament day section can not be uploaded at the time of call, HTTP 409 Conflict status code will be returned. Tournament day section may or may not be unlocked to accept fantasy lineups at a later time or date.

If user wants to use a professional player for their fantasy lineup, but they don't have a corresponding player autograph sticker for that player, then website or application may direct the user to purchase a player autograph sticker from Steam Community Market using the following URL containing the tag of the desired professional player that can be found in code field of "pro_players" schema in items_game.txt file shipped with the game:

http://steamcommunity.com/market/search?q=&category_730_ProPlayer%5B%5D=tag_getright&category_730_StickerCategory%5B%5D=tag_PlayerSignature&category_730_Tournament%5B%5D=tag_Tournament9&appid=730

Example response:

{
        "result": {
                "itemid0": 4295003892,
                "itemid1": 4295003893,
                "itemid2": 4295003894,
                "itemid3": 4295003895,
                "itemid4": 4295003896
        }
}

This response demonstrates that user's first four items preserved their itemids, but last item with itemid=4295003888 should no longer be used and a new item with itemid=4295003896 should be used instead. It is possible that all five submitted items will have different itemids returned after this call completes.

Error Handling

When website or application Steam Web API key is correct, then status code HTTP 403 Forbidden may be returned from Web API calls that require a valid steamidkey user authentication code parameter. Failing to supply a valid steamidkey user authentication code at a high rate will result in multiple subsequent calls returning status code HTTP 503 Service Unavailable even for valid steamid+steamidkey pairs.

Additionally, strict rate-limiting is applied to accommodate multiple website and application developers, so the calling website or application should be prepared to handle status codes HTTP 429 Too Many Requests and HTTP 503 Service Unavailable. When these errors are encountered then website or application should reduce the number of requests per second that they are issuing and refrain from issuing too many requests that have an invalid steamidkey user authentication code parameter.

Status code HTTP 410 Gone can be returned when placing a prediction for a particular matchup, or uploading a fantasy roster for a particular tournament day section, is no longer possible and the website or application should stop attempting those uploads.

Status code HTTP 409 Conflict can be returned when placing a prediction for a particular matchup, or uploading a fantasy roster for a particular tournament day section, is not allowed at the time of call and the website or application should stop attempting those uploads until it is known that such uploads become allowed at a later time or date. Tournament day sections may or may not be unlocked to accept predictions and fantasy lineups at a later time or date.

Status code HTTP 412 Precondition Failed can be returned when placing a prediction for a particular matchup is not allowed because previously placed upstream predictions are inconsistent with the new value, or when placing or clearing a prediction for a particular matchup is not allowed because previously placed downstream predictions depend on the prediction for that matchup. The website or application should stop attempting those uploads until user gets a chance to modify previously placed predictions to satisfy the preconditions for the matchup.

Status code HTTP 405 Method Not Allowed can be returned when requested resource is not available in the event tournament layout.

Status code HTTP 400 Bad Request will typically indicate that a combination of tournament section day, group, index or team parameters was supplied in a way that is not compatible with the event tournament layout. Website or application must validate that they have the most up to date tournament layout before submitting future requests.

Status code HTTP 404 Not Found will typically indicate that the specified itemid was not owned by the user, or wasn't representing the required team or professional player.

Status code HTTP 500 Internal Server Error typically indicates that the request failed to complete. Website or application may retry the request with the same parameters at a later time.

Status code HTTP 504 Gateway Timeout is returned when CS:GO backend server implementation timed out waiting for various asynchronous operations involving multiple backend server machines. The asynchronous operations in charge of fulfilling the request may actually complete later. Website or application may re-request tournament items, predictions, or fantasy lineups of the user in question at a later time to determine whether the request ended up completing successfully.

All other HTTP status codes should be handled by website or application according to the standard error handling protocol.

External links