Developer API Documentation - Advanced Web Ranking

Overview

The Developer API feature allows you to pull and use AWR Cloud data with any tool.

You will be able to gather keyword rankings and manage your AWR Cloud projects programmatically. All the changes made via the API will be reflected in your AWR Cloud account.

The AWR Cloud Developer API system can be accessed via standard HTTPS requests in UTF-8 format to our API endpoint: "https://api.awrcloud.com".

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 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

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. This operation 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 message such as this:

failed - can't create project, not enough keyword units (currently used: 1989, new project consumption: 924, plan max: 2000)

URL parameters

1. action=create

2. project_name=project name

usually your website's domain name. Example: www.mywebsite.com
use URL encoding and replace any space with a + sign

3. country=country ISO code

dictates number formatting preferences; also used for gathering AdWords country-specific data
use Alpha-2 codes from here

4. token=token

the API token

5. depth=5|10 (optional)

the number of pages to be retrieved from search engines - leave it blank to use the default (5)

6. frequency=daily|weekly|biweekly|monthly|ondemand (optional)

the update frequency - leave it blank to use the default (weekly)

7. teamaccess=all (optional)

whether team members shoud be given access to the project - leave it blank to use the default (don't give access to team members)

Team members have read-write access to the assigned projects. Details about the user system & types of permissions can be accessed here.

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 AWR Cloud:

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"
}

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)

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 AWR Cloud user interface.

Example POST request

https://api.awrcloud.com/sync.php?action=create&token=myAPItoken&project_name=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. This operation 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 message such as this:

failed - can't update project, not enough keyword units (currently used: 1989, exceeding amount: 2, plan max: 2000)

URL Parameters

1. action=update

2. project_name=project name

usually your website's domain name. Example: www.mywebsite.com
use URL encoding and replace any space with a + sign

3. token=token

the API token

4. teamaccess=all (optional)

whether team members shoud be given access to the project - leave it blank to use the default (don't give access to team members)

Team members have read-write access to the assigned projects. Details about the user system & types of permissions can be accessed here.

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/sync.php?action=update&token=myAPItoken&project_name=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, json

params = urllib.urlencode({"inputs": json.dumps({ "keywords" : [{"name":"my keyword 1","index":1,"color_r":0,"color_g":0,"color_b":0,"operation":0}]})})

headers = {"Content-type": "application/x-www-form-urlencoded", "Accept": "text/plain"}

token = "myAPItoken"
projectName = "project+name"

url = "www.awrcloud.com"
scriptPath = "/sync.php?action=update&token=" + token + "&project_name=" + 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/sync.php?action=update&token=myAPItoken&project_name=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/sync.php?action=update&token=" . $token . "&project_name=" . $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

1. action=get_dates

2. project_name=project name

use URL encoding and replace any space with a + sign

3. token=token

the API token

Example request

https://api.awrcloud.com/sync.php?action=get_dates&project_name=project+name&token=myAPItoken

Example output

{
  "dates":[
  {
    "date":"2013-08-01",
    "depth":"5"
  },
  {
    "date":"2013-08-02",
    "depth":"5"
  },
  {
    "date":"2013-08-03",
    "depth":"10"
  }
]
}

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 AWR Cloud. 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. This operation uses the HTTP GET method.

URL Parameters

1. action=list

2. project=project name

use URL encoding and replace any space with a + sign

3. date=yyyy-MM-dd

the date for which to retrieve data

4. token=token

the API token

5. compression=xz|zip

choose between xz (LZMA2) and ZIP

6. version=2 (optional)

returns a JSON response instead of plain text

Example request

https://api.awrcloud.com/get.php?action=list&project=project+name&date=2013-07-24&token=myAPItoken

Example output

OK
2
https://api.awrcloud.com/get.php?action=list&project=project+name&token=myAPItoken&date=2013-07-24&file=0.tar.xz
https://api.awrcloud.com/get.php?action=list&project=project+name&token=myAPItoken&date=2013-07-24&file=1.tar.xz

Output explained

First line

OK means everything went well. Any other result means there was an error:

Failed - invalid token

Failed - project missing

Second line

Indicates the number of files to retrieve (can be 0 - no data).

Daily ranking data is available each day at 12am GMT/UTC.

The output of the second line is usually 1. If, however, the size of the archived ranking file exceeds 15 MB, the response will be split into multiple files.

Third line and below

The URLs of the JSON files (one per line).

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

1. action=get

2. project=project name

use URL encoding and replace any space with a + sign

3. date=yyyy-MM-dd

the date for which you wish to retrieve data

4. token=token

the API token

5. compression=zip

leave it blank for xz (LZMA2), or use zip to get a ZIP file

6. file=the file name

the file name returned by the list ranking API call

7. version=2 (optional)

returns a JSON response instead of plain text

Example request

https://api.awrcloud.com/get.php?action=get&project=project+name&date=2013-07-24&token=myAPItoken&file=0.tar.xz

Example output

The output of the request above is a xz(LZMA2) or ZIP 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/sync.php?action=get_dates&token=" . $token . "&project_name=" . $projectName;

$response = json_decode(file_get_contents($url), true);

$dates = $response["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 AWR Cloud account. The output is returned in JSON format. This operation uses the HTTP GET method.

URL Parameters

1. action=projects

2. token=token

the API token

Example request

https://api.awrcloud.com/sync.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",
      "timestamp":1481796346
    },
    {
      "name":"mywebsite2.com",
      "id":"4",
      "frequency":"monthly",
      "depth":"5",
      "last_updated":"2016-12-07",
      "timestamp":1481769547
    }
  ]
}

The get details API call

This operation retrieves all the details of a specified project.

URL Parameters

1. action=details

2. project_name=project name

use URL encoding and replace any space with a + sign

3. token=token

the API token

Example request

https://api.awrcloud.com/sync.php?action=details&project_name=project+name&token=myAPItoken

Example output

{
  "websites":[
    {
      "name":"mywebsite1.com",
      "color_r":"0",
      "color_g":"0",
      "color_b":"255",
      "index":"1",
      "aliases":[
        "*.mywebsite1.com"
      ]
    },
    {
      "name":"mywebsite2.com",
      "color_r":"255",
      "color_g":"0",
      "color_b":"0",
      "index":"2",
      "aliases":[
        "*.mywebsite1.com"
      ]
    },
  ],
  "keywords":[
    {
      "name":"my keyword 1",
      "priority":"0",
      "color_r":"85",
      "color_g":"145",
      "color_b":"50",
      "index":"1",
      "kw_groups":[
        "my kw group 1", "my kw group 2"
        ]
    },
    {
      "name":"my keyword 2",
      "priority":"0",
      "color_r":"85",
      "color_g":"145",
      "color_b":"50",
      "index":"2",
      "kw_groups":[ ]
     }
  ],
  "searchengines":[
    {"awr_id":"1481189791"},
    {"awr_id":"1746977968"},
    {"awr_id":"241562029"}
  ]
}

Possible error codes

6: the project/website you specified does not exist

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. This operation uses the HTTP GET method.

Limit: 150 calls per hour (shared with export top sites).

URL Parameters

1. action=export_ranking

2. 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

3. token=token

the API token

4. startDate=start date

the date from which the export will start (the oldest date)
use yyyy-mm-dd format

5. stopDate=stop date

the most recent date of the export
use yyyy-mm-dd format

6. addProjectName=yes|no (optional)

whether to include the project name for each ranking data (when running for all projects)

7. version=2 (optional)

returns a JSON response instead of plain text

8. encodeurl=true (optional)

encodes URLs

Example request

https://api.awrcloud.com/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.

OK
https://api.awrcloud.com/get.php?action=get_export&token=myAPItoken&project=project+name&fileName=2013-07-23-2013-12-27

Output explained

First line

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.

Second line

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). If so, you'll receive the following response:

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/get.php?action=get_export&token=myAPItoken&project=project+name&fileName=2013-07-23-2013-12-27

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. This operation 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

1. action=get_export

2. project=project name

use URL encoding and replace any space with a + sign

3. token=token

the API token

4. fileName=startDate-stopDate

the two dates (older and newer one) separated by a dash
use yyyy-mm-dd format

5. version=2 (optional)

returns a JSON response instead of plain text

Example request

https://api.awrcloud.com/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. This operation uses the HTTP GET method.

Limit: 150 calls per hour (shared with export ranking).

URL Parameters

1. action=topsites_export

2. project=project name

use URL encoding and replace any space with a + sign

3. token=token

the API token

4. startDate=start date

the date from which the top sites export will start (the oldest date)
use yyyy-mm-dd format

5. stopDate=stop date

the most recent date of the top sites export
use yyyy-mm-dd format

6. version=2 (optional)

returns a JSON response instead of plain text

7. encodeurl=true (optional)

encodes URLs

Example request

https://api.awrcloud.com/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.

OK
https://api.awrcloud.com/get.php?action=topsites_export&token=myAPItoken&project=project+name&fileName=2013-07-23-2013-12-27

Output explained

First line

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.

Second line

If everything was ok, an URL you can shortly use to request the exported top sites.

In addition to these cases, you might request a top sites export twice (same project, same period of time). If so, you'll receive the following response:

Failed - a top sites export for this project and period has already been generated/scheduled to be generated. Fetch it using this URL:

https://api.awrcloud.com/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. This operation 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

1. action=get_topsites

2. project=project name

use URL encoding and replace any space with a + sign

3. token=token

the API token

4. fileName=startDate-stopDate

the two dates (older and newer one) separated by a dash
use yyyy-mm-dd format

5. version=2 (optional)

returns a JSON response instead of plain text

Example request

https://api.awrcloud.com/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

1. action=estimate_on_demand

2. project_name=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

3. token=token

the API token

4. speed=fast|slow

There are two types of on demand updates, depending on the estimated completion time: slow (rankings are delivered within 48h) and fast (data is available within 12h).

Example request

https://api.awrcloud.com/sync.php?action=estimate_on_demand&token=myAPItoken&project_name=["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_name":"project_name1",
      "response_code":0,
      "message":"Project is eligible for on a fast demand update",
      "used_keyword_units":8
    },
    "project_name2":{
      "project_name":"project_name2",
      "response_code":0,
      "message":"Project is eligible for on a fast demand update",
      "used_keyword_units":27.5
    }
  }
}

Output explained:

1. old_keyword_units: estimated keyword units before updating

2. new_keyword_units: estimated keyword units after updating

3. plan_keyword_units: your plan's related keyword units

4. 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

5. 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

1. action=on_demand

2. 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

3. token=token

the API token

4. speed=fast|slow

There are two types of on demand updates, depending on the estimated completion time: slow (rankings are delivered within 48h) and fast (data is available within 12h).

Example request

https://api.awrcloud.com/sync.php?action=on_demand&token=myAPItoken&project_name=["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_name":"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_name":"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:

1. old_keyword_units: keyword units before updating

2. new_keyword_units: keyword units after updating

3. plan_keyword_units: your plan's related keyword units

4. 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

5. used_keyword_units: the number of keyword units used for updating the supplied project(s)

Response Messages

If you want to receive a JSON response instead of plain text, please add the version=2 parameter. Please note that not all API calls support it.

Example request

https://api.awrcloud.com/get.php?action=export_ranking&token=myAPItoken&project=project+name&startDate=2016-12-14&stopDate=2016-12-14&version=2

Instead of plain text responses like "OK", the response will contain a JSON array:

{
  "response_code":0,
  "message":"OK",
  "details":"http://www.awrcloud.com/get.php?action=get_export&token=myAPItoken&project=project+name&fileName=2016-12-13-2016-12-14"
}

Response Codes and Messages

SUCCESS

Code: 0
Message: OK

ERROR

Code: 1
Message: An error occured. Please try again later

QUOTA EXCEEDED

Code: 2
Message: Failed - you've exhausted your quota for this hour. Please check our documentation for the limits and try again later.

ZIP NOT READY

Code: 3
Message: ZIP archive not found. Please try again later.

INVALID START DATE

Code: 4
Message: Failed - invalid start date

INVALID STOP DATE

Code: 5
Message: Failed - invalid stop date

END SMALLER START

Code: 6
Message: Failed - the end date shouldn't be smaller than the start date.

INVALID START DATE FORMAT

Code: 7
Message: Failed - invalid start date format.

INVALID STOP DATE FORMAT

Code: 8
Message: Failed - invalid stop date format.

NO UPDATES

Code: 9
Message: Failed - no update dates found in the specified interval. Please use "get_dates" and pick a valid date interval.

ITEM ALREADY EXISTS

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/get.php?action=get_export&token=myAPItoken&project=project_name&fileName=2016-05-04-2016-05-09"

INVALID TOKEN

Code: 11
Message: Failed - invalid token

API INVALID DATE

Code: 12
Message: Failed - invalid date

FILENAME MISSING

Code: 13
Message: Failed - filename missing

INVALID PROJECT

Code: 14
Message: Failed - invalid project

PROJECT MISSING

Code: 15
Message: Failed - project missing

HTML NOT FOUND

Code: 16
Message: HTML archive not found. Please try again later.

JSON NOT FOUND

Code: 17
Message: JSON archive not found. Please try again later.

INTERNAL ERROR

Code: 18
Message: Internal error. Please try again later. If this issue persists, please contact AWR Cloud support at help@awrcloud.com

API INPUT EMPTY

Code: 19
Message: Inputs parameter cannot be empty

API PROJECT ALREADY EXISTS

Code: 20
Message: Project already exists

API TS ALREADY EXISTS

Code: 21
Message: Failed - a top sites export for this project and period has already been generated/scheduled to be generated.
Details: https://api.awrcloud.com/get.php?action=get_topsites&token=myAPItoken&project=project_name&fileName=2016-05-04-2016-05-09