WebSEOAnalytics API 1 - SEO Software & Professional SEO Tools

172 Pages·2012·1.73 MB·English

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