Parsing Service

What is the Parsing Service?

The Parsing Service is a service of the Sc2gears Database where you can post a replay to a URL, and you can get back all kinds of information about the replay including basic info (like players, races, map name, duration, winners etc), the in-game chat of the players, and advanced info like APMs, EAPMs, average spawning ratio and average injection gaps of the players or the complete action list of the replay.

Or you can post the name of a StarCraft II map file, and you can get back basic info about the map and the map preview image.

Or you can get the current (live) profile info of StarCraft II players (like portrait image, achievement points, favorite race, all games, best leagues with division rank etc...).

Google Ads

Target audience

The Parsing Service is intended for sites or applications that wish to work with StarCraft II replays, but of course anyone can use the service for their needs.

Benefits

1) You can operate a replay site or a replay section on your site without the need of having a replay parser engine. You can concentrate on your site's design and logic (and leave the replay parsing logic to me).

2) Or you can use this service to validate your data. Or you might have your own replay parser engine, but you can use this to get advanced details about a game your engine is not capable of.

3) You can also ease the registration process for your users on your site by not having to enter all their battle net player data. You can ask only their Battle.net profile URL, and you can use this service to get all live profile info for that user. This also eliminates typing errors and mistakes.

4) Using the service you will take advantage of the most advanced StarCraft II replay parsing engine giving you more details and statistics about replays than any other SC2 replay parser.

5) I always try to implement replay format changes as fast as possible, which means your site will get back on feet after new StarCraft II patches much faster than other sites using custom replay parsers.

6) You do not have to give up on old replays, the service supports replay versions from 0.19 (beta) up to the current version.

7) Use of the service does not require any technology on your server (like Java) as all API calls are standard HTTP or HTTPS requests/responses. The responses are XML documents.

8) You can start multiple API calls in parallel if you want to parse a large amount of replays or get info about a large amount of maps.

9) Your servers will be freed of the computing load, and so smaller/fewer/cheaper servers will be able to serve your needs.

Sc2gears Database API User Page

The Parsing Service has a web interface where API users can view statistics of their API calls, view their Ops quota and payments, view and change their API key, and view/set basic settings like the Notification available Ops.

API call statistics are displayed for all time and broken down to each day. These statistics include the number of API calls, used Ops, average execution time, denied calls and errors count. API calls and average execution time are also tracked for each different operations.

The web interface can be reached here: Sc2gears Database API User Page

The Parsing Service Web Interface uses Google account for authentication. What does this mean?

-Google manages your account and password. They do a lot better job at keeping it safe and secure than anyone else could.

-If you have a GMail account, then you already have a Google Account. If not, you can use any email address to create a Google Account.

-Your password is never given out to any 3rd parties (unlike for example a site where you register). To Sc2gears Database Google only provides the info whether you are logged in and with which account.

-If you use other Google products (like GMail or Google Docs) and you are logged in to any of those, you will have access to your Sc2gears Database API User Page without having to log in again.

How can I register an API account to access the Parsing Service?

1) First you have to create a Google Account if you don't have one.

2) You have to send a payment of any amount to my PayPal account (email address:

Note: If you don't have a PayPal account, you can ask a friend of yours to send the money in your name.

Note #2: If PayPal is not an option for you, you can pay via bank transfer, but the transaction fee will be probably higher. Contact me for bank transfer details.

3) Send me an email (email address:

) with the following details:

- PayPal account that you sent the money from.
- Your Google account that you want to access the web interface of the Parsing Service with.
- Warning! Google account is case sensitive! Tip: Login to the Sc2gears Database API User Page, and it will display your Google account in a case sensitive manner.
- Your contact email in case it differs from the Google account you're signing up with.

4) You're done. You will receive an automated email when your account is ready. The email will contain your API key and the link to your Sc2gears Database API User Page.

You can start testing the service on the Sc2gears Database Parsing Service Tester page.

Sc2gears Database Parsing Service Tester

There is a simple HTML page where you can test the Parsing Service without having to write a single line of code. The tester page however requires a valid API key.

The tester page is available here: Sc2gears Database Parsing Service Tester

API key

API calls use an API key to authenticate and identify the API user instead of your password.

The API key is a secret key known only to its owner and to the Sc2gears Database.

The API key is sent to the users via email after registration, and you can also view your key or generate a new one on the Sc2gears Database API User Page.

If you think your API key might have been compromised, you can simply generate a new one.

You can use your API key from multiple computers, but it is your responsibility not to share it with others.

Pricing

The API calls made to the Parsing Service (may) consume Ops. The Op is the processing unit you can purchase, and it's the processing unit API calls are measured with and are charged for.

If your API call requires Ops, it will only be served if you have available Ops on your API account.

Ops are pre-paid. You can pay any amount you wish (even as little as 1 USD) at any time, and your available Ops will be increased based on your payment.

Please note that only the Net amount I receive will be converted into Ops. Tip: The transaction fee rate charged by PayPal is less if you send a bigger payment. For example if you send 1 USD via PayPal, fee amount is 0.34 USD (34%!) and I only receive 0.66 USD. If you send 30 USD, fee amount is 1.47 USD (4.9%) and I receive 28.53 USD.

Payment => Ops conversion:

1 USD = 10,000 Ops

For as little as 1 dollar you can get map info of 10,000 maps, or parse 5,000 replays (this depends on what you need from replays as the cost of parsing replays depends on the parameters you pass).

Terms of Service

Last updated: 2012-02-09

1) The payment is not refundable. You cannot change your mind and request the money back.

2) If the Parsing Service is terminated in the future, you can claim all your remaining money back (transaction fee will be applied by PayPal).

3) Price changes do not affect already paid Ops.

4) It is your responsibility to keep your Google account and your API key safe. I take no responsibility for issues arising from your Google account or your API key getting compromised.

5) Accounts abusing the service will be suspended and/or deleted. This includes -but not limited to- sharing an API key with others. Note that you may use your API key from multiple computers.

6) I reserve the right to change the terms.

Privacy Policy

Last updated: 2012-02-09

1) Replays or any other information sent to the Parsing Service are only available to the account owner and me, and are never given out to anyone else.

2) There are no individual or aggregate information collected from your API calls that would be shared with anyone else in any way.

Parsing Service API documentation

The following information is intended for developers.

The Parsing Service can be reached via standard HTTP or HTTPS calls.

The URL of the Parsing Service: https://sciigears.appspot.com/parsing

Data can be passed to the Parsing Service as standard form parameters. The service can be used either with GET or PUT requests.

GET requests can be achieved by including the parameters in the URL. Since max length of the URL is limited, this form of API call cannot be used in all cases. Also note that if the URL encoded form is used, your API key may be exposed if you do not use HTTPS protocol.

POST requests can be achieved by submitting a simple HTML form (this is what the Parsing Service Tester page does) or sending an HTTP(S) request with POST method, content type set to "application/x-www-form-urlencoded;charset=UTF-8", and all parameters may be encoded and included in the request body (after the header fields).

I recommend the use of HTTPS protocol and POST method whenever it is possible.

In general it is true that if an API call returns an HTTP error status code (different from the HTTP status code 200 (OK)), the API call will not be charged for any Ops (the call will be free).

Required parameters

There are required parameters which all API calls must send.

Protocol version: "protVer"

This is the protocol version. Current value is "1". HTTP status code 400 (BAD REQUEST) is sent back if this parameter is missing or its value is not "1".

Operation: "op"

This is the operation which specifies what you want from the service to do. HTTP status code 400 (BAD REQUEST) is sent back if this parameter is missing or its value is invalid.

API key: "apiKey"

The API key of the user. This will authenticate and identify your API user. HTTP status code 400 (BAD REQUEST) is sent back if this parameter is missing, HTTP status code 403 (FORBIDDEN) is sent back if the API key is invalid.

HTTP status code 402 (PAYMENT REQUIRED) is sent back if the associated API user does not have available Ops and the operation requires Ops.

Response format

The response of the API calls are XML documents, the content type is "text/xml", the character encoding is UTF-8.

The responses are wrapped into the "<response>" root element which has a "docVer" attribute specifying the version of the document. If incompatible changes are made to the response XML document, the value of the "docVer" attribute will be changed (incremented). Compatible changes might not result in changing its value (for example adding a new XML tag, or adding a new attribute to an existing tag).

The "<response>" element contains a "<result>" element as the first child. The "<result>" element has a "code" attribute which is the error code of the API call execution. In general a code of 0 means no error (successful API call).

The text content of the "<result>" element is a human readable message associated with the error code, "OK" in case of code 0.

Operations

Info operation: "op=info"

Info op parameters

"daysCount" (optional)
Days count specifies the count of the last days whose API call statistics to return. Must be in the range of 0..14. Default value is 2 if the parameter is missing or has an invalid value.
HTTP status code 400 (BAD REQUEST) is sent back if this parameter has a value outside of the valid range.

The info operation sends back information about the service and about the API user. These information include the parsing engine version, the server time, the paid and available Ops and the API call statistics for all time and for the last days specified by the optional daysCount parameter (which defaults to 2 if missing).

Error result codes of the info operation:

- 0 - OK: The info operation always returns a result code of 0

The info operation does not cost any Ops (the info operation is free).

Tip: You can include the result of the info operation on your site's admin page for example, so you can see your availabe Ops and usage directly in your system.

Example Info operation response XML document:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>

</callStat>

</callStat>

</callStat>

</callStats>

</response>

Map info operation: "op=mapInfo"

Map info op parameters

"mapFileName" (required)
The map file name is the SHA-256 digest of the map file content ended with an ".s2ma" extension. Example: "05db4c70e14bb9bc2702b1ffea3535bcfe3c80b69616631ded5adcd34062029c.s2ma". The following form is also accepted: "05/db/05db4c70e14bb9bc2702b1ffea3535bcfe3c80b69616631ded5adcd34062029c.s2ma" (this form is recorded in StarCraft II replay files). HTTP status code 400 (BAD REQUEST) is sent back if this parameter is missing or its value is invalid.

The Map info operation provides info about the specified map. These info include map name, map width, map height; the map preview image data size in bytes, width in pixels, height in pixels and the image data in JPEG format encoded with Base64.

The map info is acquired automatically by the system. If the requested map is not yet in the Sc2gears Database, the system automatically acquires and processes the map in the background and returns a result code of 1 - PROCESSING. Next time when this map file is queried again and if the processing is done (lets say a few seconds later) the map info will be returned properly.

Error result codes of the map info operation:

- 0 - OK: Map info is included.
- 1 - PROCESSING: Map is being processed.
- 2 - DOWNLOAD ERROR: Could not acquire map file.
- 3 - PARSING ERROR: Could not parse map file (non-standard map).

The map info operation costs 1 Op if the result code is 0. The API call does not cost any Ops if map info is not returned (if the result code is not 0).

Example Map info operation response XML document:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>

...Base64 encoded image data here...

</mapImage>

</response>

Parse replay operation: "op=parseRep"

Parse replay op parameters

"fileContent" (required)
This is the content of the replay file encoded with Base64. HTTP status code 400 (BAD REQUEST) is sent back if this parameter is missing or its value is invalid (invalid Base64 string).
"fileLength" (required)
This is the length of the replay file in bytes. Used to perform a simple check on the decoded file content. HTTP status code 400 (BAD REQUEST) is sent back if this parameter is missing or its value is not equal to the length of the decoded file content.
"parseMessages" (optional)
This optional parameter tells if the in-game chat (message events) have to be parsed. Valid values are "true" or "false". Default value is "true" if the parameter is missing or has an invalid value.
"parseActions" (optional)
This optional parameter tells if the actions of the players (game events) have to be parsed. Valid values are "true" or "false". Default value is "true" if the parameter is missing or has an invalid value.
Tip: parsing the actions will result in more statistics to be sent back, and it increases the probability to determine the proper winners.
"sendActionsSelect" (optional)
This optional parameter tells if Select actions have to be included in the response. Valid values are "true" or "false". Default value is "false" if the parameter is missing or has an invalid value.
"sendActionsBuild" (optional)
This optional parameter tells if Build actions have to be included in the response. Valid values are "true" or "false". Default value is "true" if the parameter is missing or has an invalid value.
"sendActionsTrain" (optional)
This optional parameter tells if Train actions have to be included in the response. Valid values are "true" or "false". Default value is "true" if the parameter is missing or has an invalid value.
"sendActionsResearch" (optional)
This optional parameter tells if Research actions have to be included in the response. Valid values are "true" or "false". Default value is "true" if the parameter is missing or has an invalid value.
"sendActionsUpgrade" (optional)
This optional parameter tells if Upgrade actions have to be included in the response. Valid values are "true" or "false". Default value is "true" if the parameter is missing or has an invalid value.
"sendActionsOther" (optional)
This optional parameter tells if Other actions have to be included in the response. Valid values are "true" or "false". Default value is "false" if the parameter is missing or has an invalid value. Other actions include all actions that are not covered by the rest of the categories.
"sendActionsInaction" (optional)
This optional parameter tells if Inaction actions have to be included in the response. Valid values are "true" or "false". Default value is "false" if the parameter is missing or has an invalid value.

The parse replay operation parses and extracts all kind of information from the replay file passed as the value of the "fileContent" parameter. Supported replay versions are: from 0.19 (beta) to 1.4.3 (current version).

Please note that even if you don't need the actions, parsing the actions ("parseActions=true") will result in more statistics to be sent back (like APM, EAPM, avg spawning ratio etc.), and it increases the probability to determine the proper winners. If you really don't need the actions, you can specify not to send the actions to decrease the XML size and get the response faster. The con of parsing the replays is that you get the results slightly slower and it costs more Ops (see below).

If actions are parsed and requested to be sent back, they will be put in the "<actions>" element in chronological order. Each action has a "<a>" element with the following attributes:

- "f": action frame
- "p": player index performing the action
- "t": First letter of the action type (S=Select, T=Train, B=Build, R=Research, U=Upgrade, O=Other, I=Inaction)
- "s": string representation of the action

Example: <a f="392" p="1" s="Train Drone" t="T"/>

Error result codes of the parse rep operation:

- 0 - OK: Replay is parsed successfully.
- 1 - PARSING ERROR: Could not parse replay file.

The "pure" parse replay operation costs 1 Op. The call costs another 1 Op if actions are parsed ("parseActions=true").

The call costs antother 1 Op if actions are parsed AND Select actions or Other actions are requested to be sent back ("sendActionsSelect=true" OR "sendActionsOther=true").

The call costs antother 1 Op if actions are parsed AND Inaction actions are requested to be sent back ("sendActionsInaction=true").

To sum it up:

- The parse replay operation costs a minimum of 1 Op ("parseActions=false").
- The parse replay operation with default parameters costs 2 Ops ("parseActions=true" AND "sendActionsSelect=false" AND "sendActionsOther=false" AND "sendActionsInaction=false").
- The parse replay operation costs a maximum of 4 Ops ("parseActions=true" AND ("sendActionsSelect=true" OR "sendActionsOther=true") AND "sendActionsInaction=true").

Example Parse replay operation response XML document with the default parameters:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>

</clients>

</player>

</player>

</players>

</repInfo>

</inGameChat>

...more actions continue here...

</actions>

</response>

Profile info operation: "op=profInfo"

Profile info op parameters

"bnetProfileUrl" (optionally required)
- Battle.net profile URL of the player. If provided, this will be used to identify the player whose profile info to be retrieve. HTTP status code 400 (BAD REQUEST) is sent back if this parameter is provided and its value is invalid.
"bnetId" (optionally required)
- Battle.net id of the player. HTTP status code 400 (BAD REQUEST) is sent back if "bnetProfileUrl" is not provided and this parameter is missing or its value is invalid.
"bnetSubid" (optionally required)
- Battle.net sub-id of the player (region identifier). HTTP status code 400 (BAD REQUEST) is sent back if "bnetProfileUrl" is not provided and this parameter is missing or its value is invalid.
"gateway" (optionally required)
- 2-letter gateway code of the player. Vaild values are: "US" - America, "EU" - Europe, "KR" - Asia, "CN" - China, "SG" - South-East Asia. HTTP status code 400 (BAD REQUEST) is sent back if "bnetProfileUrl" is not provided and this parameter is missing or its value is invalid.
"playerName" (optionally required)
- Name of the player (case sensitive). HTTP status code 400 (BAD REQUEST) is sent back if "bnetProfileUrl" is not provided and this parameter is missing.
"retrieveExtInf" (optional)
- - This optional parameter tells if extended profile info is needed to be retrieved and sent back. Extended profile info includes all team rank information (not just the best ranks) with team member names. Valid values are "true" or "false". Default value is "false" if the parameter is missing or has an invalid value.

The Profile info operation retrieves the current (live) profile info of the specified player from the Battle.net server. These include the portrait, achievement points, games played current season, total career games, most played mode, most played race, highest solo finish league plus times achieved, highest team finish league plus times achieved. If extended profile info is requested, all teams info will be included grouped by game format (league, division rank and team member names), inside of a group teams are order by league and division rank descending (from best ranked teams to worst) . If a team info (not 1v1) contains only 1 member, that means it's a random team.

The player whose profile info to be retrieved can be specified in 2 ways: either with providing the "bnetProfileUrl" parameter, or providing the "bnetId", "bnetSubid", "gateway" and "playerName" parameters. If the "bnetProfileUrl" parameter is provided, it will be used and the mentioned other 4 parameters are disregarded.

If you want to query the profile of a player taken from the output of the parse rep operation, all parameter values can be found as the attributes of the "playerId" XML tag.

The portrait is defined by 3 numbers: portrait group, portrait column, portrait row. Portraits are presented from big images which contain a group of portrait images. This group is specified by the portrait group. A portrait group image contains the portraits in a table or matrix with 6 rows and 6 columns. A portrait is appointed by the the column and the row in this table, these are the portrait column and portrait row. The row and column is in the range of 0..5. The portrait group images can be downloaded from here: portraits.zip (updated: 2013-02-20). This zip file contains the portrait group images in different sizes (45x45, 75x75, 90x90 pixels of individual portraits).

Error result codes of the profile info operation:

- 0 - OK: Profile info is retrieved and included.
- 1 - BNET_ERROR: Could not connect to Battle.net.
- 2 - INVALID_PLAYER: Invalid player specified.
- 3 - PARSING ERROR: Could not parse data from Battle.net.

The Profile info operation costs 3 Ops by default if extended profile info is not requested ("retrieveExtInf=false"), and it costs 6 Ops if extended profile info is requested ("retrieveExtInf=true").

If the result code is not OK (code is not 0), the cost is 1 Op if extended profile info is not requested, and 2 Ops if extended profile info is requested. (Note that if the returned HTTP status code is not 200 (OK), the call will still cost 0 Ops.)

If extended profile info is requested, and base profile info is successfully retrieved but retrieval of the extended profile info fails, result code will be OK (code=0), base profile info will be sent back, and 4 Ops will be charged.

Example Profile info operation response XML document with extra profile info retrieved:

</teamMembers>

</teamRank>

</allRankGroup>

</teamRank>

</teamMembers>

</teamRank>

</allRankGroup>

</teamMembers>

</teamRank>

</teamMembers>

</teamRank>

</teamMembers>

</teamRank>

</allRankGroup>

</teamMembers>

</teamRank>

</teamMembers>

</teamRank>

</allRankGroup>

</allRankGroups>

</profInfo>

</response>