Web SEO Analytics – Documentation – WSA API 1.21v WSA API 1.21v Introduction Web SEO Analytics (WSA) offers a "REST-Like" RPC-style API for creating innovative Web solutions and services based on WebSEOAnalytics.com SEO Tools. This service allows the SEO Professionals, Online Marketing Agencies & Web Development Companies to create Branded SEO Reports for their clients and to build new innovative Web Services & SEO Tools. The following documentation describes how to use the WSA API and it is divided into the following sections: What is new on WSA API 1.21v: This section describes the updates that have been made in the WSA API 1.21v. Web Service Description: The Web Service Description section describes how to get started and what basic information you should know about the WSA API. API Reference: The API Reference contains details about the WSA Web Service, including the Actions, the authentication method and other elements that make up the Application Programming Interface (API). Appendix: The Appendix section contains the table of the Supported SEO Tools & Tool IDs, information about the Error Messages, the SEO Tool Inputs, the SEO Tool Responses, the supported Search Engine Languages Codes and the Resource Center where you can find and download code samples. In order to use the WSA API, you must sign up for a WSA account and acquire a Paid Subscription. Using the WSA SEO Tools, the WSA API or the Website indicates that you have read and accept the Terms & Conditions and the Privacy Policy. If you do not accept these terms, you are not authorized to use this website. Page 1 of 172 Web SEO Analytics – Documentation – WSA API 1.21v What is new on WSA API 1.21v? The new 1.21 Version of the toolbox focuses on improving the speed of the service. Minor algorithmic updates are also included in this version changing slightly the way that WebzyRank and WuzzRank are calculated. Additionally due to the close down of a 3rd party service that powered up the Aged Domain Finder few of the filters of the tool were removed (filter by AlexaRank, PageRank and Age in Years). The new version 1.21 is backwards compatible with version 1.20 and as a result it replaced the previous API version. This means that all the API users that used the 1.20 version will now automatically access the 1.21v without updating their API clients. The tools that have been updated/added in the 1.21 version are:  Aged Domain Finder: Removal of the ability to filter domains by AlexaRank, PageRank and Age in Years. New SalesType and updated salesCategory values. More information about the new features can be found on the SEO Tool Responses segment of this manual. Please note that in order to perform any API Action with the 1.21 version you need to send your HTTP POST requests to the following URLs: http://www.webseoanalytics.com/api/1.2/ [Action-URL-Here] Finally note that the current Toolbox contains several new features and tools that are still in beta. As a result some of them might not be available on future versions of the toolbox. All the beta features & tools are marked with (beta) while all the updated tools and features are marked with (updated). Finally the removed features on the updated tools are marked with (removed). Page 2 of 172 Web SEO Analytics – Documentation – WSA API 1.21v Web Service Description This section describes how to get started and what basic information you should know about the WSA API. The steps in order to use the Web Service are: 1. Sign up for a Web SEO Analytics account. 2. Acquire a Paid Subscription & get your API Key. 3. Download the code samples from the Resource Center. 4. Follow the instructions in the API Reference to configure and execute the code samples. Request & Response Type The WSA Web Service supports HTTP POST requests and returns the result in XML and JSON (beta) format. Additionally the WSA API allows requesting the SEO reports in PDF and CSV format. Rate Limits Our service rate limits are imposed as a limit on the number of new Reports that can be created by the user of a WSA Subscription during a specific time period (window of time). The most common rate limit that is used in WSA service is the maximum number of daily reports. This means that within a 24-hour window, the user can generate maximum X number of reports with a particular tool. The exact time period and limitations depend on the Subscription that has been acquired by the user. If the user account has multiple subscriptions, then different rate limits are imposed based on the subscription that is used. Page 3 of 172 Web SEO Analytics – Documentation – WSA API 1.21v API Reference This section describes the WSA Web Service, including the Actions, the authentication method and other elements that make up the Application Programming Interface (API). What can I do with the WSA API? The WSA API allows you to access the SEO Tools and manage the SEO Reports by performing several Actions. Each Action that is listed below contains at least one sample request in order to help you get started. Use the sample requests as a starting point for developing your own requests. Have in mind that before using the sample codes you need to acquire a Paid Subscription, get your API Key and configure your authentication data within the code. By using the API you can perform the following Actions: 1. Authentication: The WSA Web Service is a stateless web service and thus the authentication process takes place in every request. 2. viewSubscriptions: Get a list of all the active WSA subscriptions of the user account. 3. viewLimits: Get a list of all the limitation rules that are imposed on a given WSA subscription for a particular tool. It also provides the number of reports that have been executed so far and the maximum allowed reports per tool. 4. viewList: Get the list of all the previously generated Reports of a particular SEO Tool. 5. deleteReport: Delete a previously generated Report. 6. viewReport: Get the data of a previously generated Report. 7. newReport: Create a new Report by using one of the supported SEO Tools. Page 4 of 172 Web SEO Analytics – Documentation – WSA API 1.21v Authentication The WSA Web Service is a stateless web service and thus the authentication process takes place in every request. This means that all the parameters that are related to the authentication process must be present in all the requests. The API Key The main authentication data needed in order to access the WSA Web Service are the User ID and the API Key. Both of these data can be found in the API area which is located in your Profile. In addition to the authentication data, in order to be able to use the API you need to have an active Paid Subscription. The API Key is a unique key that is used in order to create the Authentication Key which is actually sent during authentication process. The API Key is linked to every account and it must be kept secret from any unauthorized person. It is your responsibility to maintain the API Key secret and you must contact immediately WebSEOAnalytics.com if you become aware of any loss, theft or any unauthorized use of your API Key. The Authentication Parameters and the Authentication Process In order to successfully authenticate to the WSA Web Service each request must contain the following parameters: Name Description userID The unique numeric ID of the user. The Authentication Key which is produced by combining the API Key, authKey the userID and the timestamp (See below). The Unix timestamp for the current time of the request. It is highly timestamp recommended to generate it for GMT timezone. Example Request: userID=10&authKey=XzXuCp%2BxcDLoGu04pzDAo4l2JWQ%3D&timestamp=12 70000775 Important Notice: Every request parameter value must be url encoded. The Authentication Key (authKey) parameter changes in each request and it remains valid for a predefined time period. In order to calculate the authKey parameter of the request you need to concatenate the userID parameter with a new line (\n) and with the timestamp (for example: userID+"\n"+timestamp). Then you calculate the binary HMAC SHA1 hash of the previous string by using your API Key. Finally in order to ensure that all the characters of the hash will be transmitted correctly you need to encrypt it with the base64 encryption. Page 5 of 172 Web SEO Analytics – Documentation – WSA API 1.21v Below you will find a pseudo-grammar that illustrates the procedure: TEMPVAR = userID + "\n" + timestamp; HASHVAR = HMAC-SHA1(TEMPVAR, APIKEY); authKey = base64(HASHVAR); Here is the same code in PHP: <?php $binary=true; $tempvar = $userID."\n".$timestamp; $hash = hash_hmac('sha1',$tempvar,$apiKey, $binary); $authKey = base64_encode($hash); ?> Here is the same code in C# .NET: private string GetAuthKey(long timestamp, string userID, string apiKey) { HMACSHA1 hmac = new HMACSHA1(); hmac.Key = Encoding.UTF8.GetBytes(apiKey); string string2sign = userID + "\n" + timestamp.ToString(); return Convert.ToBase64String(hmac.ComputeHash(Encoding.UTF8.GetBytes(string2sign))); } By following the above procedure and by using the authKey to authenticate to the WSA Web Service you minimize the risk of compromising your secret API Key. Have in mind that the above authentication process is not a step that is done once per session but every time you call the WSA API. Thus the above 3 parameters (userID, authKey and timestamp) must be present in all of your requests and the authKey should be calculated every time you submit a new request. Page 6 of 172 Web SEO Analytics – Documentation – WSA API 1.21v viewSubscriptions The Web SEO Analytics service allows every user to have multiple package subscriptions under the same account. Every subscription can be linked to a different SEO pack and it can have different limitations and settings. By using the WSA API you are able to get a list of all the active subscriptions of your user account and use this data when you call the other Actions. Note that the list of all the active subscriptions of your account can also be found on the API area of your profile. Service URL In order to perform the viewSubscriptions Action you need to send a HTTP POST request to the following URL: http://www.webseoanalytics.com/api/1.2/viewSubscriptions.php Request Parameters Name Description The format of the Response. The viewList supports the 2 basic formats: format xml and json The language of the Response. This affects the language of the messages that are printed in the Report. Currently only English is supported. lang Allowed values: EN The Callback Function to wrap the response. This is an optional parameter callback that can be used only with json Output Format. Have in mind that the Authentication Variables must always be present in the request. Example of POST Request parameters: userID=10&authKey=XzXuCp%2BxcDLoGu04pzDAo4l2JWQ%3D&timestamp=12 70000775&format=json&lang=EN&callback=myfunction Response Below you can find the list of all the fields that are included within the Response: Name Description It appears always once and it includes the other fields of the ResultSet Response. version It is a string that stores the version of the response (the (attribute of current API version). ResultSet) It is a Boolean value which indicates whether an error status occurred or not. output It contains the output of the Request. Page 7 of 172 Web SEO Analytics – Documentation – WSA API 1.21v Name Description It is a list of subscriptions and it contains multiple entry subscriptionList elements. If no active subscriptions are available this tag is empty. It groups together all the information that is relevant to the entry particular subscription entry. The ID of the Subscription. The id of a Professional subscriptionID Subscription should be used as an input parameter when you call the other Actions. packageID The ID of the Package of the Subscription. A brief & user-friendly description that is used to identify the packageName particular Package. Example of a Successful XML Response: <?xml version="1.0" encoding="UTF-8"?> <ResultSet version="1.21"> <status>1</status> <output> <subscriptionList> <entry> <subscriptionID>1</subscriptionID> <packageID>0</packageID> <packageName>Free User</packageName> </entry> <entry> <subscriptionID>2</subscriptionID> <packageID>1</packageID> <packageName>PRO Plan</packageName> </entry> </subscriptionList> </output> </ResultSet> Example of a Successful JSON Response: { "ResultSet":{ "@attributes":{ "version":"1.21" }, "status":"1", "output":{ "subscriptionList":{ "entry":[ { "subscriptionID":"1", "packageID":"0", "packageName":"Free User" }, { "subscriptionID":"2", "packageID":"1", "packageName":"PRO Plan" } ] } } } } Page 8 of 172 Web SEO Analytics – Documentation – WSA API 1.21v Note that in JSON Response the attributes of a particular element are marked with "@attributes". If you have defined a Callback Function the JSON Response will look like this: myfunction({ json response goes here }) Page 9 of 172 Web SEO Analytics – Documentation – WSA API 1.21v viewLimits The rate limits of the subscriptions are imposed on the number of new Reports generated with a particular tool during a predifined timeframe. The limitations and the policies vary depending on the SEO Pack of your subscription. The viewLimits Action allows you to find the number of reports that you have generated with a specific tool within a particular period. By having this information you can calcuate the remaining usages of a tool using the specific subscription. Service URL In order to perform the viewLimits Action you need to send a HTTP POST request to the following URL: http://www.webseoanalytics.com/api/1.2/viewLimits.php Request Parameters Name Description The format of the Response. The viewList supports the 2 basic format formats: xml and json The language of the Response. This affects the language of the messages that are printed in the Report. Currently only English is lang supported. Allowed values: EN The Callback Function to wrap the response. This is an optional callback parameter that can be used only with json Output Format. The subscription ID for which you want to check the limitations. subscriptionID You can find this ID by performing the viewSubscriptions Action. The ID of the SEO Tool for which you want to check the toolID limitations. Check the Supported SEO Tools & Tool IDs. Have in mind that the Authentication Variables must always be present in the request. Example of POST Request parameters: userID=10&authKey=XzXuCp%2BxcDLoGu04pzDAo4l2JWQ%3D&timestamp=12 70000775&format=xml&lang=EN&subscriptionID=2&toolID=12 Response Below you can find the list of all the fields that are included within the Response: Name Description It appears always once and it includes the other fields of ResultSet the Response. Page 10 of 172