Overview
The Developer API feature allows you to pull and use Advanced Web Ranking data with any tool.
You will be able to gather keyword rankings and manage your Advanced Web Ranking projects programmatically. All the changes made via the API will be reflected in your Advanced Web Ranking account.
The Advanced Web Ranking Developer API system can be accessed via standard HTTPS requests in UTF-8 format to our API endpoint: "https://api.awrcloud.com/v2/get.php".
The Developer API feature is available for all types of Yearly plans and, for monthly subscriptions, starting with Agency and higher.
All the accounts have a default limit of 2,000 API calls per hour for most operations, unless specified otherwise. If you need this limit increased, feel free to contact us.
The Developer API V.2. shares the same accessibility characteristics and limitations as API V.1.
The following API Operations are available:
- create project - create a project/website
- update project - modify keywords, search engines, etc. for an existing project
- get dates - retrieve all the dates that a project has ranking data for
- list ranking - find out if there is ranking data available for a certain day
- get ranking - download ranking data for a certain day
- get projects - retrieve account projects
- get details - retrieve project details
- export ranking - schedule a ranking data export
- get export - download a ranking data export
- export top sites - schedule a top sites export
- get top sites - download a top sites export
- estimate on demand update - estimate how many keyword units an on demand update would use
- request on demand update - request an on demand update
- delete projects - delete projects
- export gwt - schedule a google webmaster tools export
- get gwt export - download a google webmaster tools export
- export visibility - schedule a visibility export
- get visibility - download a visibility export
- export ctr - exports google organic ctr data for a given month
The create project API call
This operation allows you to create a project / website and specify the search engines, keywords and websites / competitors that it will contain. It uses the HTTP POST method.
Limit: 60 calls per hour (60 seconds delay between requests).
The call will fail if your account can't accomodate the project you're trying to create. If this happens, you'll receive a response like this:
{
"response_code":26,
"message":"failed - can't create project, not enough keyword units (currently used: 1989, new project consumption: 924, plan max: 2000)"
}
URL parameters
- action = create
- project = project name
- Usually your website's domain name. Example: www.mywebsite.com
- Use URL encoding and replace any space with a + sign
- country = country ISO code
- Dictates number formatting preferences; also used for gathering AdWords country-specific data
- Use Alpha-2 codes from here
- token = token
- The API token
- depth = 5|10 (optional)
- The number of pages to be retrieved from search engines - leave it blank to use the default (5)
- frequency = daily|weekly|biweekly|monthly|ondemand (optional)
- The update frequency - leave it blank to use the default (weekly)
POST parameters
inputs=
{
"keywords":[Keyword1, Keyword2,…, KeywordN],
"searchengines":[SearchEngine1, SearchEngine1,…, SearchEngineN],
"websites":[Website1, Website2,…, WebsiteN]
}
Where Keyword 1 is the first keyword we would like to add and has the following format:
{
"name":"my keyword",
"index":3,
"color_r":0,
"color_g":0,
"color_b":255,
"kw_groups":["my kw group 1","my kw group 2"]
}
- name = the keyword name
- index = number – The order in which the keyword will be displayed in reports (when sorting by index)
- color_r = 0..255 – The red component of the keyword color
- color_g = 0..255 – The green component of the keyword color
- color_b = 0..255 – The blue component of the keyword color
- kw_groups = the names of the keyword groups – The keyword groups in which you want to place this keyword
The following parameters are optional: index, color_r, color_g, color_b, kw_groups - so you can just specify the name of the keyword, and it will be added with a default color, it will use the next available index and it won't be included in any keyword groups. Example:
{"name":"my keyword"}
Search engine types
There are two types of search engines that you can add in Advanced Web Ranking:
- Predefined search engines
- Location search engines
Adding a predefined search engine
{"awr_id":2138589785}
- awr_id = number – The search engine's ID. You can find the supported search engine IDs list here (second column).
Adding a location search engine
This type of search engine is useful for tracking keyword rankings in a specific location, such as San Francisco, CA. It will return the same results as someone searching from that location.
{
"name":"google",
"country":"US",
"location":"San Francisco, CA",
"language":"en",
"se_type":"desktop news"
}
- name = string – The search engine name. Only "Google" is currently supported
- country = string – The country. Click here to get a list of available countries (first column)
- location = string – The location. Example: San Francisco, CA
- language = string – The language. Click here to get a list of available languages (first column)
- se_type = string – The search engine type. Click here to get a list of available types (first column)
When defining location search engines, the se_type parameter is optional. When the results type to be tracked is not specified, the search engine will be inserted with the default preference, which is Organic and Places.
Website1 is the first website we would like to add and should look like this:
{
"name":"mysite.com",
"aliases":"*.mysite.com",
"index":1,
"color_r":0,
"color_g":0,
"color_b":255,
"pages":[]
}
- name = string – The website domain
- aliases = string – Other domains, subdomains or URLs that you want matched with your domain. You should at least provide *.mydomain.com, otherwise we'll only match the exact domain you use for the name parameter when running updates
- index = number – The order in which the keyword will be displayed in the reports (when sorting by index)
- color_r = 0..255 – The red component of the website color
- color_g = 0..255 – The green component of the website color
- color_b = 0..255 – The blue component of the website color
- pages = Page1, Page2,..., PageN – This website's pages you would like to track
The following parameters are optional: index, color_r, color_g, color_b, pages, so you can just specify the name of the website, and it will be added with a default color and the next index available. The default page that will be tracked is the index page, or "/". Example: {"name":"mysite.com"}
The first website you add will be used as the main project website. Any other websites will be shown as competitors in the Advanced Web Ranking user interface.
Example POST request
https://api.awrcloud.com/v2/get.php?action=create&token=myAPItoken&project=project+name&country=US
POST parameters
inputs=
{
"keywords":[
{
"name":"my keyword 1",
"index":3,
"color_r":0,
"color_g":0,
"color_b":255,
"kw_groups":[
"kw_group1",
"kw_group1"
]
},
{
"name":"my keyword 2",
"index":3,
"color_r":0,
"color_g":0,
"color_b":255,
"kw_groups":[
"kw_group2",
"kw_group3"
]
}
],
"searchengines":[
{
"awr_id":2138589785
},
{
"awr_id":1481189791
},
{
"name":"google",
"country":"US",
"location":"San Francisco, CA",
"language":"en"
}
],
"websites":[
{
"name":"mysite.com",
"aliases":"*.mysite.com,",
"color_r":0,
"color_g":0,
"color_b":255,
"index":1,
"pages":[
]
},
{
"name":"competitor.com",
"aliases":"*.competitor.com,",
"color_r":255,
"color_g":0,
"color_b":0,
"index":2,
"pages":[
]
}
]
}
PHP code sample
<?php
$token = "myAPItoken";
$projectName = "project+name";
$keywords = array();
$kwGroups1 = array(
"kw_group1",
"kw_group2"
);
$kwGroups2 = array(
"kw_group2",
"kw_group3"
);
$keyword1 = array(
"name" => "My keyword",
"index" => 1,
"color_r" => 0,
"color_g" => 0,
"color_b" => 0,
"kw_groups" => $kwGroups1
);
$keyword2 = array(
"name" => "My second keyword",
"index" => 2,
"color_r" => 0,
"color_g" => 0,
"color_b" => 0,
"kw_groups" => $kwGroups2
);
$keywords[] = $keyword1;
$keywords[] = $keyword2;
$searchEngines = array();
// predefined search engines
$aol = array(
"awr_id" => 64990
);
$bing = array(
"awr_id" => 1481189791
);
// custom search engine
$googleWithLocation = array(
"name" => "google",
"country" => "US",
"location" => "San Francisco, CA",
"language" => "en"
);
$searchEngines[] = $aol;
$searchEngines[] = $bing;
$searchEngines[] = $googleWithLocation;
$websites = array();
$website = array(
"name" => "mysite.com",
"aliases" => "*.mysite.com",
"color_r" => 0,
"color_g" => 0,
"color_b" => 0,
"index" => 1
);
$competitor = array(
"name" => "mycompetitor.com",
"aliases" => "*.mycompetitor.com",
"color_r" => 0,
"color_g" => 0,
"color_b" => 0,
"index" => 2
);
$websites[] = $website;
$websites[] = $competitor;
$inputs = array(
"keywords" => $keywords,
"websites" => $websites,
"searchengines" => $searchEngines
);
$depth = 5;
$country = "US";
$frequency = "daily";
$url = "https://api.awrcloud.com/sync.php?action=create&token=" . $token . "&project_name=" . $projectName . "&country=" . $country . "&frequency=" . $frequency . "&depth=" . $depth;
$data = array(
"inputs" => json_encode($inputs)
);
$options = array(
"http" => array(
"header" => "Content-type: application/x-www-form-urlencoded\r\n",
"method" => 'POST',
"content" => http_build_query($data)
)
);
$context = stream_context_create($options);
$result = file_get_contents($url, false, $context);
switch ($result)
{
case "0":
die("Success");
case "2":
die("Invalid API token");
case "4":
die("Inputs parameter cannot be empty");
case "5":
die("Project already exists");
default:
die("Unknown response: " . $result);
}
?>
The update project API call
This operation allows you to modify some project inputs, such as keywords, search engines etc. for an existing project. It uses the HTTP POST method to send all parameters in a JSON format.
This call cannot start a ranking update.
This call will fail if your account can't accomodate any inputs you may be trying to add (new keywords/search engines), if you're opting for a higher frequency or more depth. If this happens, you'll receive a response like this:
{
"response_code":26,
"message":"failed - can't update project, not enough keyword units (currently used: 1989, exceeding amount: 2, plan max: 2000)"
}
URL Parameters
- action = update
- project = project name
- Usually your website's domain name. Example: www.mywebsite.com
- Use URL encoding and replace any space with a + sign
- token = token
- The API token
POST parameters
inputs=
{
"keywords":[Keyword1, Keyword2,..., KeywordN],
"searchengines":[SearchEngine1, SearchEngine1,..., SearchEngineN],
"websites":[Website1, Website2,..., WebsiteN]
}
Where Keyword1 is the first keyword we would like to modify and should look like this:
{
"name":"my keyword",
"operation":1,
"index":3,
"color_r":0,
"color_g":0, "color_b":255
}
- name = the keyword name
- operation = 0..2 – The operation: 0 = add / 1 = remove / 2 = update
- index = number – The order in which the keyword will be displayed in the reports (when sorting by index)
- color_r = 0..255 – The red component of the keyword color
- color_g = 0..255 – The green component of the keyword color
- color_b = 0..255 – The blue component of the keyword color
The following parameters are optional: index, color_r, color_g, color_b.
PHP example request for adding two keywords
https://api.awrcloud.com/v2/get.php?action=update&token=myAPItoken&project=project+name
POST parameters
inputs=
{
"keywords":[
{
"name":"my keyword 1",
"operation":0
},
{
"name":"my keyword 2",
"operation":0
}
],
"searchengines":[
],
"websites":[
]
}
Python code sample for adding a keyword
import httplib, urllib
params = urllib.urlencode({"inputs": { "keywords" : [{"name":"my keyword 1","index":1,"color_r":0,"color_g":0,"color_b":0,"operation":0}]}})
params = params.replace("%27", "%22") #make sure to use double quotes, not single ones
headers = {"Content-type": "application/x-www-form-urlencoded", "Accept": "text/plain"}
token = "myAPItoken"
projectName = "project+name"
url = "api.awrcloud.com"
scriptPath = "/v2/get.php?action=update&token=" + token + "&project=" + projectName + "&country=US&frequency=daily&depth=5";
conn = httplib.HTTPConnection(url, 80)
conn.request("POST", scriptPath, params, headers)
response = conn.getresponse()
print("sending request: " + params)
data = response.read()
print("got response: " + data)
conn.close()
Example request for updating the color of a keyword
https://api.awrcloud.com/v2/get.php?action=update&token=myAPItoken&project=project+name
POST parameters
inputs=
{
"keywords":[
{
"name":"my keyword 1",
"operation":2,
"color_r":0,
"color_g":0,
"color_b":255
}
],
"searchengines":[
],
"websites":[
]
}
PHP code sample for updating a project/website
Removing keywords from keyword groups is not currently possible via the API - you can only assign them to new ones.
<?php
define("ADD_OPERATION", 0);
define("REMOVE_OPERATION", 1);
define("EDIT_OPERATION", 2);
$token = "myAPItoken";
$projectName = "project+name";
$keywords = array();
$removedKeyword = array(
"name" => "My keyword",
"index" => 1,
"color_r" => 0,
"color_g" => 0,
"color_b" => 0,
"operation" => REMOVE_OPERATION
);
// change color and add to two keyword groups
$kwGroups2 = array(
"keyword group 1",
"keyword group 2"
);
$editedKeyword = array(
"name" => "My second keyword",
"index" => 2,
"color_r" => 0,
"color_g" => 128,
"color_b" => 0,
"operation" => EDIT_OPERATION,
"kw_groups" => $kwGroups2
);
$kwGroups3 = array(
"keyword group 3"
);
$addedKeyword = array(
"name" => "My third keyword",
"index" => 3,
"color_r" => 0,
"color_g" => 0,
"color_b" => 0,
"operation" => ADD_OPERATION,
"kw_groups" => $kwGroups3
);
$keywords[] = $removedKeyword;
$keywords[] = $editedKeyword;
$keywords[] = $addedKeyword;
$searchEngines = array();
$aol = array(
"awr_id" => 64990,
"operation" => REMOVE_OPERATION
);
$altavista = array(
"awr_id" => 1465793403,
"operation" => ADD_OPERATION
);
$searchEngines[] = $aol;
$searchEngines[] = $altavista;
$inputs = array(
"keywords" => $keywords,
"searchengines" => $searchEngines
);
$url = "https://api.awrcloud.com/v2/get.php?action=update&token=" . $token . "&project=" . $projectName;
$data = array(
'inputs' => json_encode($inputs)
);
$options = array(
'http' => array(
'header' => "Content-type: application/x-www-form-urlencoded\r\n",
'method' => 'POST',
'content' => http_build_query($data)
)
);
$context = stream_context_create($options);
$result = file_get_contents($url, false, $context);
switch ($result)
{
case "0":
die("Success");
case "2":
die("Invalid API token");
case "4":
die("Inputs parameter cannot be empty");
default:
die("Unknown response.");
}
?>
The get dates API call
This operation retrieves all the dates that a project has ranking data for. The output is returned in JSON format.
URL Parameters
- action = get_dates
- project = project name
- Use URL encoding and replace any space with a + sign
- token = token
- The API token
Example request
https://api.awrcloud.com/v2/get.php?action=get_dates&project=project+name&token=myAPItoken
Example output
{
"response_code":0,
"message":"OK",
"details":{
"dates":[
{
"date":"2014-04-15",
"depth":"5"
},
{
"date":"2014-04-16",
"depth":"5"
}
]
}
}
Depth is the number of pages that were retrieved from the Search Engine. Possible values are 5 and 10. This call will only return dates for updates performed by Advanced Web Ranking. Imported historical updates (from AWR Desktop or import files) will not be listed and cannot be accessed via API calls.
The list ranking API call
This operation is used to find out if there is data for a certain day. It returns one or more URLs, which you will need to retrieve using the get ranking operation below. It uses the HTTP GET method.
URL Parameters
- action = list
- project = project name
- Use URL encoding and replace any space with a + sign
- The date for which to retrieve data
- token = token
- The API token
- compression = xz|zip
- Choose between xz (LZMA2) and ZIP
Example request
https://api.awrcloud.com/v2/get.php?action=list&project=project+name&date=2013-07-24&token=myAPItoken
Example output
{
"response_code":0,
"message":"OK",
"details":"https://api.awrcloud.com/v2/get.php?action=get&project=project+name&token=myAPItoken&date=2013-07-24&type=json&compression=&file=0.tar.xzhttps://api.awrcloud.com/v2/get.php?action=get&project=project+name&token=myAPItoken&date=2013-07-24&type=json&compression=&file=1.tar.xz"
}
Output explained
Message
OK means everything went well. Any other result means there was an error:
Failed - invalid token
Failed - project missing
Daily ranking data is available each day at 12am GMT/UTC.
Details
The URLs of the JSON files - they're glued together.
The get ranking API call
This operation is used to download ranking data for a specific day. The data is delivered as a LZMA or ZIP archive containing JSON files. Use the list ranking API call above to get these URLs.
URL Parameters
- action = get
- project = project name
- Use URL encoding and replace any space with a + sign
- date = yyyy-MM-dd
- The date for which you wish to retrieve data
- token = token
- The API token
- compression = zip
- Leave it blank for xz (LZMA2), or use zip to get a ZIP file
- file = the file name
- The file name returned by the list ranking API call
Example request
https://api.awrcloud.com/v2/get.php?action=get&project=project+name&date=2013-07-24&token=myAPItoken
Example output
The output of the request above is a LZMA or ZIP archive containing a JSON file.
PHP code example to retrieve rankings
This example uses the get dates to get all available ranking dates for a project and then the list ranking and get ranking API calls to get the actual JSON files containing the rankings.
<?php
$projectName = "project+name";
$token = "myAPItoken";
$url = "https://api.awrcloud.com/v2/get.php?action=get_dates&token=" . $token . "&project=" . $projectName;
$response = json_decode(file_get_contents($url), true);
$dates = $response["details"]["dates"]; // date and search depth arrays
foreach ($dates as $dateAndDepth)
{
$date = $dateAndDepth["date"];
$depth = $dateAndDepth["depth"];
$url = "https://api.awrcloud.com/get.php?action=list&project=" . $projectName . "&date=" . $date . "&token=" . $token . "&compression=zip";
$rankingResultsResponse = file_get_contents($url);
$responseRows = explode("\n", $rankingResultsResponse);
if ($responseRows[0] != "OK")
{
echo "No results for date: " . $date;
continue;
}
$dateFilesCount = $responseRows[1];
if ($dateFilesCount == 0)
{
continue;
}
for ($i = 0; $i < $dateFilesCount; $i++)
{
$urlRequest = $responseRows[2 + $i];
$urlHandle = fopen($urlRequest, 'r');
$tempZip = fopen("tempfile.zip", "w");
while (!feof($urlHandle))
{
$readChunk = fread($urlHandle, 1024 * 8);
fwrite($tempZip, $readChunk);
}
fclose($tempZip);
fclose($urlHandle);
$pathToExtractedJson = "path/to/extracted/jsons/";
$zip = new ZipArchive;
$res = $zip->open("tempfile.zip");
if ($res === FALSE)
{
echo "Could not extract JSON files from the zip archive";
continue;
}
$zip->extractTo($pathToExtractedJson);
$zip->close();
$dir_handle = opendir($pathToExtractedJson);
while (false !== ($entry = readdir($dir_handle)))
{
if ($entry == ".." || $entry == ".")
{
continue;
}
$rankings = json_decode(file_get_contents($pathToExtractedJson . $entry), true); // the json file contains nested json objects, make sure you use associative arrays
echo "
";
echo "
Search Engine: " . $rankings["searchengine"];
echo "
Search Depth: " . $rankings["depth"];
echo "
Location: " . $rankings["location"];
echo "
Keyword: " . $rankings["keyword"];
$rank_data_array = $rankings["rankdata"];
foreach ($rank_data_array as $rank_data)
{
echo "<br/>" . $rank_data["position"] . ". " . $rank_data["url"] . " " . $rank_data["typedescription"] . " result on page " . $rank_data["page"];
}
}
}
}
?>
The get projects API call
This operation retrieves the names of all projects/websites that exist in your Advanced Web Ranking account. The output is returned in JSON format. It uses the HTTP GET method.
URL Parameters
- action = projects
- token = token
- The API token
Example request
https://api.awrcloud.com/v2/get.php?action=projects&token=myAPItoken
Example output
The output of the request above is a JSON with the following contents:
{
"projects":[
{
"name":"mywebsite1.com",
"id":"1",
"frequency":"weekly",
"depth":"5",
"last_updated":"2016-12-14",
"kwcount": "34",
"main_website": "www.mywebsite1.com",
"timestamp":1481796346
},
{
"name":"mywebsite2.com",
"id":"4",
"frequency":"monthly",
"depth":"5",
"last_updated":"2016-12-07",
"kwcount": "43",
"main_website": "www.mywebsite2.com",
"timestamp":1481769547
}
]
}
The get details API call
This operation retrieves all the details of a specified project.
URL Parameters
- action = details
- project = project name
- Use URL encoding and replace any space with a + sign
- token = token
- The API token
Example request
https://api.awrcloud.com/v2/get.php?action=details&project=project+name&token=myAPItoken
Example output
{
"websites":[
{
"name":"mysite.com",
"color_r":"0",
"color_g":"0",
"color_b":"0",
"index":"1",
"aliases":[
"*.mysite.com"
]
},
{
"name":"mycompetitor.com",
"color_r":"0",
"color_g":"0",
"color_b":"0",
"index":"2",
"aliases":[
"*.mycompetitor.com"
]
}
],
"keywords":[
{
"name":"My keyword",
"priority":"0",
"color_r":"0",
"color_g":"123",
"color_b":"196",
"index":"1",
"added_on":"2016-07-05",
"kw_groups":[
"kw_group1",
"kw_group2"
]
},
{
"name":"My second keyword",
"priority":"0",
"color_r":"54",
"color_g":"154",
"color_b":"61",
"index":"2",
"added_on":"2016-07-05",
"kw_groups":[
"kw_group2",
"kw_group3"
]
}
],
"prefs":[
],
"searchengines":[
{
"awr_id":"64990"
},
{
"awr_id":"1481189791"
},
{
"awr_id":"25809237"
}
],
"locations":[
{
"type":"1",
"host":"Google.com",
"language":"en",
"country":"US",
"location":"San Francisco, CA"
}
]
}
Possible error codes
15: the project/website you specified does not exist
11: the API token is invalid
The export ranking API call
This operation schedules a ranking export for one or all projects over a supplied period of time and returns the URL at which you'll find the exported file. It uses the HTTP GET method.
Limit: 150 calls per hour (shared with export top sites, export gwt and export visibility).
URL Parameters
- action = export_ranking
- project = project name (optional)
- Not adding it will generate a ZIP file containing ranking exports for all projects
- Use URL encoding and replace any space with a + sign
- token = token
- The API token
- startDate = start date
- The date from which the export will start (the oldest date)
- Use yyyy-mm-dd format
- stopDate = stop date
- The most recent date of the export
- Use yyyy-mm-dd format
- addProjectName = yes|no (optional)
- Whether to include the project name for each ranking data
- encodeurl = true (optional)
- Encodes URLs
- format = csv|json (optional)
- Leave it blank to use the default (CSV)
Example request
https://api.awrcloud.com/v2/get.php?action=export_ranking&project=project+name&token=myAPItoken&startDate=2013-07-23&stopDate=2013-12-27
Example output
The output of the request above is an URL which you can use to request the file after it's been generated.
{
"response_code":0,
"message":"OK",
"details":"https://api.awrcloud.com/v2/get.php?action=get_export&token=myAPItoken&project=project+name&fileName=2013-07-23-2013-12-27"
}
Output explained
Message
OK - any other result means there was an error:
- Failed - invalid token
- Failed - project missing
- Failed - invalid project
- Failed - invalid start date
- Failed - invalid stop date
- Failed - the end date shouldn't be smaller than the start date
- Failed - you've exhausted your quota for this hour. Please check our documentation for the limits and try again later.
- Failed - no update dates found in the specified interval. Please use "get_dates" and pick a valid date interval.
- Failed - an unknown error has occurred. Please try again later.
Details
If everything was ok, an URL you can shortly use to download the exported ranking.
In addition to these cases, you might request an export twice (same project, same period of time, same options). If so, you'll receive the following response:
{
"response_code":10,
"message":"Failed - an export for this project and period has already been generated/scheduled to be generated. Fetch it using this URL:",
"details":"https://api.awrcloud.com/v2/get.php?action=get_export&token=myAPItoken&fileName=2013-07-23-2013-12-2"
}
You can use the provided link to download it.
The get export API call
This operation is used to download a previously scheduled ranking export. It uses the HTTP GET method.
Make sure to use the export_ranking API call before! It also provides the exact link you need for this operation.
URL Parameters
- action = get_export
- project = project name
- Use URL encoding and replace any space with a + sign
- token = token
- The API token
- fileName = startDate-stopDate
- The two dates (older and newer one) separated by a dash
- Use yyyy-mm-dd format
Example request
https://api.awrcloud.com/v2/get.php?action=get_export&token=myAPItoken&project=project+name&fileName=2013-07-23-2013-12-27
Example response
If everything is OK, your download should start and look like this.
Output explained
If you do get a response without a download starting, it should be one of these errors:
- Failed - invalid token
- Failed - project missing
- Failed - invalid project
- Failed - filename missing
- Export in progress. Please come back later
The export top sites API call
This operation schedules a top sites export for a project over a supplied period of time and returns the URL at which you'll find the exported file. It uses the HTTP GET method.
Limit: 150 calls per hour (shared with export ranking, export gwt and export visibility).
URL Parameters
- action = topsites_export
- project = project name
- Use URL encoding and replace any space with a + sign
- token = token
- The API token
- startDate = start date
- The date from which the export will start (the oldest date)
- Use yyyy-mm-dd format
- stopDate = stop date
- The export's most recent date
- Use yyyy-mm-dd format
- encodeurl = true (optional)
- Encodes URLs
Example request
https://api.awrcloud.com/v2/get.php?action=topsites_export&project=project+name&token=myAPItoken&startDate=2013-07-23&stopDate=2013-12-27
Example output
The output of the request above is an URL which you can use to request the file after it's been generated.
{
"response_code":0,
"message":"OK",
"details":"https://api.awrcloud.com/v2/get.php?action=get_topsites&token=myAPItoken&project=project+name&fileName=2013-07-23-2013-12-27"
}
Output explained
Message
OK - any other result means there was an error:
- Failed - invalid token (the token you supplied is invalid)
- Failed - project missing (the project could not be found)
- Failed - invalid project (no project name was specified)
- Failed - invalid start date (the supplied start date is invalid)
- Failed - invalid stop date (the supplied stop date is invalid)
- Failed - the end date shouldn't be smaller than the start date
- Failed - you've exhausted your quota for this hour. Please check our documentation for the limits and try again later.
- Failed - no update dates found in the specified interval. Please use "get_dates" and pick a valid date interval.
- Failed - an unknown error has occurred. Please try again later.
Details
If everything was ok, an URL you can shortly use to request the exported file.
In addition to these cases, you might request a top sites export twice (same project, same period of time, same options). If so, you'll receive the following response:
{
"response_code":10,
"message":"Failed - an export for this project and period has already been generated/scheduled to be generated. Fetch it using this URL:
",
"details":"https://api.awrcloud.com/v2/get.php?action=get_topsites&token=myAPItoken&project=project+name&fileName=2013-07-23-2013-12-27"
}
You can use the provided link to download it.
The get top sites API call
This operation is used to download a previously scheduled top sites export. It uses the HTTP GET method.
Make sure to use the export top sites API call before! It also provides the exact link you need for this operation.
URL Parameters
- action = get_topsites
- project = project name
- Use URL encoding and replace any space with a + sign
- token = token
- The API token
- fileName = startDate-stopDate
- The two dates (older and newer one) separated by a dash
- Use yyyy-mm-dd format
Example request
https://api.awrcloud.com/v2/get.php?action=get_topsites&token=myAPItoken&project=project+name&fileName=2013-07-23-2013-12-27
Example response
If everything is OK, your download should start and look like this.
Output explained
If you do get a response without a download starting, it should be one of these errors:
- Failed - invalid token
- Failed - project missing
- Failed - invalid project
- Failed - filename missing
- Export in progress. Please come back later
The estimate on demand update API call
This operation indicates the number of keyword units required by an on demand update for one or more projects. The output is returned in JSON format.
URL Parameters
- action = estimate_on_demand
- project = project name|multiple projects in JSON format
- The name of your project, or, if you want to get estimates for updating multiple projects, a JSON array with the project names: "project_name1","project_name2","project_name3"
- Use URL encoding and replace any space with a + sign
- token = token
- The API token
- speed = fast|slow
There are two types of on demand updates, depending on the estimated completion time: slow (rankings are delivered within 7 days) and fast (data is available within 24h).
Example request
https://api.awrcloud.com/v2/get.php?action=estimate_on_demand&token=myAPItoken&project=["project_name1","project_name2"]&speed=slow
Example output
{
"old_keyword_units":"2215",
"new_keyword_units":2250.5,
"plan_keyword_units":14500,
"websites":{
"project_name1":{
"project":"project_name1",
"response_code":0,
"message":"Project is eligible for on a fast demand update",
"used_keyword_units":8
},
"project_name2":{
"project":"project_name2",
"response_code":0,
"message":"Project is eligible for on a fast demand update",
"used_keyword_units":27.5
}
}
}
Output explained:
- old_keyword_units = estimated keyword units before updating
- new_keyword_units = estimated keyword units after updating
- plan_keyword_units = your plan's related keyword units
- response_code =
- 0: OK
- 1: your website has already been queued for a ranking update today
- 2: quota exceeded
- 3: fast update daily quota exceeded
- 4: slow update weekly quota exceeded
- 5: project does not exist
- 6: you cannot request on demand updates for more than 50 projects at once
- used_keyword_units = the estimated number of keyword units used for updating the supplied project(s)
The request on demand update API call
This operation requests an on demand update for one or multiple projects. The output is returned in JSON format.
URL Parameters
- action = on_demand
- project = project name|multiple projects in JSON format
- The name of your project, or, if you want to update multiple projects, a JSON array with the project names: "project_name1","project_name2","project_name3"
- Use URL encoding and replace any space with a + sign
- token = token
- The API token
- speed = fast|slow
There are two types of on demand updates, depending on the estimated completion time: slow (rankings are delivered within 7 days) and fast (data is available within 24h).
Example request
https://api.awrcloud.com/v2/get.php?action=on_demand&token=myAPItoken&project=["project_name1","project_name2"]&speed=slow
Example output
{
"old_keyword_units":"2215",
"new_keyword_units":2250.5,
"plan_keyword_units":14500,
"websites":{
"project_name1":{
"project":"project_name1",
"response_code":0,
"message":"Your project_name1 website has been queued for a Fast ranking update. You will see the results in less than 24 hours.",
"used_keyword_units":8
},
"project_name2":{
"project":"project_name2",
"response_code":0,
"message":"Your project_name2 website has been queued for a Fast ranking update. You will see the results in less than 24 hours.",
"used_keyword_units":27.5
}
}
}
Output explained:
- old_keyword_units: keyword units before updating
- new_keyword_units: keyword units after updating
- plan_keyword_units: your plan's related keyword units
- response_code:
- 0: OK
- 1: your website has already been queued for a ranking update today
- 2: quota exceeded
- 3: fast update daily quota exceeded
- 4: slow update weekly quota exceeded
- 5: project does not exist
- 6: you cannot request on demand updates for more than 50 projects at once
- used_keyword_units: the number of keyword units used for updating the supplied project(s)
The delete projects API call
This operation allows you to delete a list of projects.
URL Parameters
- action = delete_projects
- token = token
- The API token
POST Parameters
inputs=
{
"projects":[{"name":"project1"},{"name":"project2"},{"name":"project3"}]
}
Where project1, project2, project3 are the names of the projects you want to delete.
Example request
https://api.awrcloud.com/v2/get.php?action=delete_projects&token=myAPItoken
Example output
{
"response_code":0,
"message":"OK",
"details":{
"projects":[
{
"name":"project1",
"status":0
},
{
"name":"project2",
"status":0
},
{
"name":"project3",
"status":0
}
]
}
}
A JSON with the same list of projects and a status for each project.
- 0: for a successfully deleted project
- 15: for a project that is no longer available
PHP code example to delete some projects
<?php
$projects = array();
$prj1 = array("name" => "project1");
$prj2 = array("name" => "project2");
$prj3 = array("name" => "project3");
$projects[] = $prj1;
$projects[] = $prj2;
$projects[] = $prj3;
$inputs = array("projects" => $projects);
$token = "myAPItoken";
$url = "https://api.awrcloud.com/v2/get.php?action=delete_projects&token=" . $token";
$data = array('inputs' => json_encode($inputs));
$curl = curl_init();
curl_setopt($curl,CURLOPT_URL, $url);
curl_setopt($curl,CURLOPT_POST, sizeof($data));
curl_setopt($curl,CURLOPT_POSTFIELDS, $data);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
$result = curl_exec($curl);
curl_close($curl);
print_r($result);
?>
The export gwt API call
This operation allows you to generate a Google Webmaster Tools export.
Limit: 150 calls per hour (shared with export ranking, export top sites and export visibility).
URL Parameters
- action = gwt_export
- token = token
- The API token
- project = project name
- Use URL encoding and replace any space with a + sign
- startDate = start date
- The date from which the export will start (the oldest date)
- Use yyyy-mm-dd format
- stopDate = stop date
- The most recent date of the export
- Use yyyy-mm-dd format
- device = device type
- 1 - all devices
- 2 - desktop
- 3 - mobile
- 4 - tablet
- 5 - desktop vs mobile
- 6 - desktop vs tablet
- 7 - mobile vs tablet
Example request
https://api.awrcloud.com/v2/get.php?action=gwt_export&token=myAPItoken&project=project+name&device=1&startDate=2013-07-23&stopDate=2013-12-27
Example output
{
"response_code":0,
"message":"OK",
"details":"https://api.awrcloud.com/v2/get.php?action=get_gwt&token=myAPItoken&project=project+name&fileName=myFileName"
}
The file name is generated as "project name-gwt-api-startDate-stopDate-device".
Output explained
Message
OK - any other result means there was an error:
- Failed - invalid token
- Failed - project missing
- Failed - invalid project
- Failed - invalid start date
- Failed - invalid stop date
- Failed - the end date shouldn't be smaller than the start date
- Failed - an unknown error has occurred. Please try again later.
Details
If everything was ok, an URL you can shortly use to request the exported Google Webmaster Tools metrics.
In addition to these cases, you might request a Google Webmaster Tools export twice (same project, same period of time, same options). If so, you'll receive the following response:
{
"response_code":10,
"message":"Failed - an export for this project and period has already been generated/scheduled to be generated. Fetch it using this URL:",
"details":"https://api.awrcloud.comm/v2/get.php?action=get_gwt&token=myAPItoken&project=project+name&fileName=project name-gwt-api-2013-07-23-2013-12-27-1"
}
Example output
If everything is OK, your export should start being generated. When finished, you can find the google webmaster tools export in a zipped CSV file with the following columns: Keyword, Clicks Opportunities, Impressions, Impressions Change, Clicks, Clicks Change, Avg Position, Avg Position Change, CTR, CTR Change.
The get gwt export API call
This operation allows you to download a previously generated Google Webmaster Tools export.
Make sure to use the export gwt API call before! It also provides the exact link you need for this operation.
URL Parameters
- action = get_gwt
- token = token
- fileName = project name-gwt-api-startDate-stopDate-device, Where
- project name - do NOT replace space characters with + signs
- The two dates (older and newer one) separated by a dash, use yyyy-mm-dd format
- The device (see the above api request for valid values for the device parameter)
Example request
https://api.awrcloud.com/v2/get.php?action=get_gwt&token=myAPItoken&project=project+name&fileName=project name-gwt-api-2013-07-23-2013-12-27-4
Example output
If everything is OK, your download should start.
The export visibility API call
This operation schedules a visibility export that compares two update dates and returns the link at which you'll find the zipped CSV file.
Limit: 150 calls per hour (shared with export ranking, export top sites and export gwt).
URL Parameters
- action = visibility_export
- project = project name
- token = token
- The API token
- startDate = start date
- The date to compare the exported metrics with
- Use yyyy-mm-dd format
- stopDate = stop date
- The date for which to export the metrics
- Use yyyy-mm-dd format
- keywordgroup = keyword group (optional)
- The keyword group for which to export the metrics
- Use the keyword group's name. You can find the available keyword groups for this project via the get details API call.
- searchengine = search engine (optional)
- The search engine for which to export the metrics
- Use the search engine's ID. You can find the available search engines IDs for this project via the get details API call.
- alldates = false|true (optional)
- Use true value to export visibility metrics for all dates in the startDate - stopDate interval. Leave it blank to use the default (false) and export export visibility metrics for stopDate compared with the startDate.
Example request
https://api.awrcloud.com/v2/get.php?action=visibility_export&project=project+name&token=myAPItoken&startDate=2013-07-23&stopDate=2013-12-27
Example output
The output of the request above is an URL which you can use to request the file after it's been generated.
{
"response_code":0,
"message":"OK",
"details":"https://api.awrcloud.com/v2/get.php?action=get_visibility&token=myAPItoken&project=project+name&fileName=visibility_api-project name_2013-07-23-2013-12-27"
}
Output explained
Message
OK - any other result means there was an error:
- Failed - invalid token
- Failed - project missing
- Failed - invalid project
- Failed - invalid start date
- Failed - invalid stop date
- Failed - invalid search engine
- Failed - invalid keyword group
- Failed - the end date shouldn't be smaller than the start date
- Failed - you've exhausted your quota for this hour. Please check our documentation for the limits and try again later.
- Failed - no update dates found in the specified interval. Please use "get_dates" and pick a valid date interval.
- Failed - an unknown error has occurred. Please try again later.
Details
If everything was ok, an URL you can shortly use to request the exported file.
In addition to these cases, you might request an export twice (same project, same period of time). If so, you'll receive the following response:
{
"response_code":10,
"message":"Failed - an export for this project and period has already been generated/scheduled to be generated. Fetch it using this URL:",
"details":"https://api.awrcloud.com/v2/get.php?action=get_visibility&token=myAPItoken&project=project+name&fileName=visibility_api-project name_2013-07-23-2013-12-27"
}
You can use the provided link to download it.
The get visibility API call (new)
This operation is used to download a previously scheduled visibility export. This operation uses the HTTP GET method.
Make sure to use the export visibility API call before! It also provides the exact link you need for this operation.
URL Parameters
- action = get_visibility
- project = project name
- Use URL encoding and replace any space with a + sign
- token = token
- The API token
- fileName = visibility_api-project name_startDate-stopDate
- The project name
- The two dates (older and newer one) separated by a dash
- Use yyyy-mm-dd format
Example request
https://api.awrcloud.com/v2/get.php?action=get_visibility&token=myAPItoken&fileName=visibility_api-project_2015-07-01-2015-07-22
Example response
If everything is OK, your download should start. When finished, the visibility export looks like the example below:
All Search Engines - All Keyword Groups
Metric | mysite.com | mycompetitor1.com | mycompetitor2.com |
---|---|---|---|
Visibility Score | 40 (13) | 39 (39) | 77 (-2) |
Visibility Percent | 44.44 (-0.56) | 43.33 (43.33) | 85.56 (-2.22) |
Average Rank | 17.67 (0.17) | 41.33 (-59.67) | 5.33 (0.67) |
On First Page | 0 (-) | 1 (1) | 3 (-) |
Below First Page | 3 (1) | 2 (-1) | 0 (-) |
First Place | 0 (-) | 0 (-) | 0 (-) |
Top 3 | 0 (-) | 0 (-) | 0 (-) |
Top 5 | 0 (-) | 0 (-) | 2 (-1) |
Top 10 | 0 (-) | 1 (1) | 3 (-) |
Top 20 | 2 (-) | 2 (2) | 3 (-) |
Top 30 | 3 (1) | 2 (2) | 3 (-) |
Ranked | 3 (1) | 2 (2) | 3 (-) |
Not Ranked | 0 (-) | 1 (-2) | 0 (-) |
Moved Up | 0 (-) | 2 (2) | 1 (-) |
Moved Down | 2 (-) | 0 (-) | 0 (-) |
Added | 0 (-) | 2 (2) | 1 (-) |
Dropped | 0 (-) | 0 (-) | 0 (-) |
Net Gain | 0 (-) | 79 (79) | 44 (-2) |
Net Loss | 8 (-1) | 0 (-) | 0 (-) |
Click Share | 0 (-) | 0.51 (0.51) | 5.31 (-) |
Estimated Visits | 0 (-) | 0 (1) | 1 (-) |
Output explained
If you do get a response without a download starting, it should be one of these errors:
- Failed - invalid token
- Failed - project missing
- Failed - invalid project
- Failed - filename missing
- ZIP archive not found. Please try again later.
The export ctr API call
This operation exports the Google CTR curve data, for a given month, as JSON or CSV. The data set is built using the Click-through rates of various keywords and websites.
URL Parameters
- action = export_ctr
- token = token
- The API token
POST Parameters
inputs=
{
"date":"my date1",
"searches-type":"my search type",
"value":"my value",
"device":"my device",
"audience":"my audience",
"format":"my format",
}
- date = yyyy-mm-dd - The month to export CTR data for
- searches-type = allSearches|branded|search-intent|long-tail|categories – Breaks down the CTR data on the search type
- value = exact|average – The position in search results
- device = allDevices|desktop|mobile|tablet (optional) - Filters on the specified device type the search was conducted on, leave it blank to use the default (allDevices)
- audience = international|us (optional) - Filters CTR data against the specified location the search originated from, leave it blank to use the default (international)
- format = csv|json (optional) - Format of the exported CTR data, leave it blank to use the default (csv)
Example request
https://api.awrcloud.com/v2/get.php?action=export_ctr&token=dd3189dc6a4f28d4596adff4cd285b47&inputs={"date":"2019-04-15","searches-type":"allSearches","value":"exact","format":"json"}
Example output
The output of the request above is below.
{
"response_code":0,
"message":"OK",
"details":[
{"position":"1","web_ctr":"34.4009","web_ws":"47562","web_kws":"788315","mobile_ctr":"28.7185","mobile_ws":"47561","mobile_kws":"1522963"},
{"position":"2","web_ctr":"17.3079","web_ws":"41394","web_kws":"614290","mobile_ctr":"16.453","mobile_ws":"47646","mobile_kws":"1185182"},
{"position":"3","mobile_ctr":"10.5373","mobile_ws":"41852","mobile_kws":"997643","web_ctr":"10.3999","web_ws":"40656","web_kws":"589808"},
{"position":"4","web_ctr":"6.888","web_ws":"41293","web_kws":"574306","mobile_ctr":"7.0689","mobile_ws":"41930","mobile_kws":"912321"},
{"position":"5","mobile_ctr":"4.9757","mobile_ws":"42686","mobile_kws":"838709","web_ctr":"4.8993","web_ws":"42102","web_kws":"546054"},
{"position":"6","mobile_ctr":"3.5952","mobile_ws":"44260","mobile_kws":"767339","web_ctr":"3.6127","web_ws":"42930","web_kws":"502292"},
{"position":"7","web_ctr":"2.7454","web_ws":"43888","web_kws":"460380","mobile_ctr":"2.6546","mobile_ws":"45502","mobile_kws":"704813"},
{"position":"8","web_ctr":"2.1637","web_ws":"44168","web_kws":"413271","mobile_ctr":"2.0431","mobile_ws":"46354","mobile_kws":"634697"},
{"position":"9","mobile_ctr":"1.582","mobile_ws":"45656","mobile_kws":"542885","web_ctr":"1.7437","web_ws":"43751","web_kws":"355266"},
{"position":"10","mobile_ctr":"1.1994","mobile_ws":"41946","mobile_kws":"365207","web_ctr":"1.4801","web_ws":"41138","web_kws":"260132"},
{"position":"11","mobile_ctr":"1.0041","mobile_ws":"33234","mobile_kws":"172006","web_ctr":"1.4603","web_ws":"37011","web_kws":"165285"},
{"position":"12","mobile_ctr":"1.2038","mobile_ws":"23050","mobile_kws":"66431","web_ctr":"1.6965","web_ws":"33129","web_kws":"107798"},
{"position":"13","web_ctr":"1.7355","web_ws":"29848","web_kws":"78796","mobile_ctr":"1.468","mobile_ws":"17459","mobile_kws":"36767"},
{"position":"14","web_ctr":"1.6101","web_ws":"27786","web_kws":"65157","mobile_ctr":"1.6306","mobile_ws":"14617","mobile_kws":"26108"},
{"position":"15","web_ctr":"1.4708","web_ws":"26134","web_kws":"56050","mobile_ctr":"1.7097","mobile_ws":"12934","mobile_kws":"20772"},
{"position":"16","web_ctr":"1.3481","web_ws":"24646","web_kws":"49711","mobile_ctr":"1.7499","mobile_ws":"11654","mobile_kws":"17728"},
{"position":"17","web_ctr":"1.2082","web_ws":"23638","web_kws":"44869","mobile_ctr":"1.7559","mobile_ws":"10802","mobile_kws":"15623"},
{"position":"18","web_ctr":"1.1478","web_ws":"23121","web_kws":"41930","mobile_ctr":"1.6904","mobile_ws":"10171","mobile_kws":"14271"},
{"position":"19","web_ctr":"1.0435","web_ws":"22436","web_kws":"39186","mobile_ctr":"1.6747","mobile_ws":"9658","mobile_kws":"13233"},
{"position":"20","web_ctr":"0.9596","web_ws":"21767","web_kws":"36738","mobile_ctr":"1.5768","mobile_ws":"9092","mobile_kws":"12374"}
]
}
Response codes and messages
Response | Code | Message |
---|---|---|
SUCCESS | 0 | OK |
ERROR | 1 | An error occured. Please try again later |
QUOTA EXCEEDED | 2 | Failed - you've exhausted your quota for this hour. Please check our documentation for the limits and try again later. |
ZIP NOT READY | 3 | ZIP archive not found. Please try again later. |
INVALID START DATE | 4 | Failed - invalid start date |
INVALID STOP DATE | 5 | Failed - invalid stop date |
END SMALLER START | 6 | Failed - the end date shouldn't be smaller than the start date. |
INVALID START DATE FORMAT | 7 | Failed - invalid start date format. |
INVALID STOP DATE FORMAT | 8 | Failed - invalid stop date format. |
NO UPDATES | 9 | Failed - no update dates found in the specified interval. Please use get_dates and pick a valid date interval. |
ITEM ALREADY EXISTS | 10 | Failed - an export for this project and period has already been generated/scheduled to be generated. Fetch it using this URL: https://api.awrcloud.com/v2/get.php?action=get_export&token=api_token&project=project_name&fileName=2016-05-04-2016-05-09 |
INVALID TOKEN | 11 | Failed - invalid token |
API INVALID DATE | 12 | Failed - invalid date |
FILENAME MISSING | 13 | Failed - filename missing |
INVALID PROJECT | 14 | Failed - invalid project |
PROJECT MISSING | 15 | Failed - project missing |
HTML NOT FOUND | 16 | HTML archive not found. Please try again later. |
JSON NOT FOUND | 17 | JSON archive not found. Please try again later. |
INTERNAL ERROR | 18 | Internal error. Please try again later. If this issue persists, please contact Advanced Web Ranking support at help@awrcloud.com |
API INPUT EMPTY | 19 | Inputs parameter cannot be empty |
API PROJECT ALREADY EXISTS | 20 | Project already exists |
INVALID API REQUEST | 29 | Failed - the requested API call is not available. |