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...).
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.
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.
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
-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.
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:
You can start testing the service on the Sc2gears Database Parsing Service Tester page.
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 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.
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.
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).
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.
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.
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).
There are required parameters which all API calls must send.
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".
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.
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.
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.
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:
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.
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:
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).
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:
Error result codes of the parse rep operation:
The "pure" parse replay operation costs 1 Op. The call costs another 1 Op if actions are parsed ("parseActions=true").
To sum it up:
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:
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.