Developer API v2

API System 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 the following endpoints:

• https://api.awrcloud.com/v2/get.php - enabled for basic project management actions or exporting tracked project ranking data. The current endpoint works for all AWR API calls, except Market Share API calls.
• https://api.awrcloud.com/api/marketshare/v1/endpoint.php - enabled for Market Share API requests.

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

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

1. action = create
2. project = 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)
   • Specify whether team members shoud be given access to the project - leave it blank to use the default (don't give access to team members)

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

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

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":[]
}

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.

{
  "response_code":26,
  "message":"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 = 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)
   • Specify whether team members shoud be given access to the project - leave it blank to use the default (don't give access to team members)

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
}

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, 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 = "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

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

1. action = projects
2. 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

1. action = details
2. project = project name
   • Use URL encoding and replace any space with a + sign
3. 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 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 = project name
   • Use URL encoding and replace any space with a + sign
3. 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"
      }
    ]
  }
}

The delete projects API call

This operation allows you to delete a list of projects.

URL Parameters

1. action = delete_projects
2. 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 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 = 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 = ultrafast|fast|slow

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:

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: Quota exceeded! Update cannot be started.
   • 2: An update is already in progress.
   • 3: Ultrafast updates are unavailable during trial.
   • 4: Ultrafast quota exceeded. Update cannot be started.
   • 5: An error has occurred while estimating your on demand update.
   • 6: On-demand option does not exist. Update cannot be started.
   • 7: Project does not exist. Update cannot be started.
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 = ultrafast|fast|slow

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:

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: Quota exceeded! Update cannot be started.
   • 2: An update is already in progress.
   • 3: Ultrafast updates are unavailable during trial.
   • 4: Ultrafast quota exceeded. Update cannot be started.
   • 5: An error has occurred while running your on demand update.
   • 6: On-demand option does not exist. Update cannot be started.
   • 7: Project does not exist. Update cannot be started.
5. used_keyword_units: the number of keyword units used for updating the supplied project(s)

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

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

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

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

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

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

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
7. encodeurl = true (optional)
   • Encodes URLs
8. format = csv|json (optional)
   • Leave it blank to use the default (CSV)
9. searchEngineId = search engine id (optional)
   • -1 for All Search Engines (default)
   • or one from your project
10. keywordGroupId = keyword group id (optional)
    • -1 for All Keywords (default)
    • -2 for Branded
    • -3 for Non-Branded
    • or one from your project

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 - invalid search engine ID.
• Failed - invalid keyword group ID.
• 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.

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

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

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 export will start (the oldest date)
   • Use yyyy-mm-dd format
5. stopDate = stop date
   • The export's most recent date
   • Use yyyy-mm-dd format
6. encodeurl = false | true (optional)
   • Encodes URLs
   • Defaults to encodeurl = false
7. topUrls = number of URLs (optional)
   • Specify the number of URLs to export
   • The value must be numeric
   • Defaults to all URLs
8. searchEngine = search engine (optional)
   • Search engine/search engines IDs
   • Either provide one id or an array of IDs
   • Use the search engine's ID. You can find the available search engines IDs for this project via the get search engines API call.
   • Defaults to all search engines
9. keywordGroupId = keyword group id (optional)
   • Keyword group/keyword groups IDs
   • Either provide one id or an array of IDs
   • Use the keyword group's ID. You can find the available keyword groups IDs for this project via the get keyword groups API call.
   • Defaults to all keyword groups
10. keywordGroupName = keyword group name (optional)
    • Keyword group/keyword groups names
    • Either provide one name or an array of names
    • An alternative for keywordGroupId parameter
    • Can be applied only if the keywordGroupId parameter is not provided
    • Defaults to all keyword groups
11. sponsored = false | true (optional)
    • Include/exclude sponsored results
    • Defaults to sponsored = true, where the ads will be included in exported data
12. resultType = result type (optional)
    • The result types to be included
    • Filters the exported data to particularly include the URLs of certain result type/s
    • Either provide one result type or an array of result types
    • The following result types are available:
      • featured snippets (includes all subtypes: paragraph, list, table, video)
      • featured snippets paragraph
      • featured snippets list
      • featured snippets table
      • featured snippets video
      • sitelinks
      • top stories
      • images
      • knowledge panel
      • videos
      • tweets
      • local pack
      • people also ask
      • carousel
      • direct answer
      • recipes
      • sponsored (can be added only if the sponsored parameter is not set to false)
      • reviews
      • faq
13. pixelPosition = false | true (optional)
    • Include\exclude pixel position column from export
    • Defaults to pixelPosition = false, where the column will not be included in exported data.
14. xlsx = false | true (optional)
    • Export as XLSX
    • Defaults to xlsx = false, and the exported data is in CSV format. Use xlsx = true to get the exported data in XLSX format.

Example request

https://api.awrcloud.com/v2/get.php?action=topsites_export&project=project+name&token=myAPItoken&startDate=2021-03-15&stopDate=2021-03-17&keywordGroupId=5&resultType=["sitelinks","top+stories","people+also+ask","reviews"]&pixelPosition=true&topUrls=10&searchEngine=3806

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=project+name_top_sites_2021-03-15-2021-03-17_Google.com+Desktop+Universal_3690230fb8781295cafc4dfa254a544c"
}

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.
• Failed - an error has occurred. Please add at least a valid keyword group or an array of groups.
• Failed - an error has occurred. The keyword groups with the ids (group 1 id, group 2 id) are not added to your project.
• Failed - an error has occurred. The keyword groups (group 1 name, group 2 name) are not added to your project.
• Failed - an error has occurred. Encodeurl parameter is invalid.
• Failed - an error has occurred. TopUrls parameter must be numeric.
• Failed - an error has occurred. Sponsored parameter is invalid.
• Failed - an error has occurred. Xlsx parameter is invalid.
• Failed - an error has occurred. PixelPosition parameter is invalid.
• Failed - an error has occurred. Please add at least a valid search engine or an array of search engines.
• Failed - an error has occurred. The search engines with the ids (search engine 1 id, search engine 2 id) are not added to your project.
• Failed - an error has occurred. Please add at least a valid result type or an array of result types.
• Failed - an error has occurred. Sponsored is true but is not in the result type array.
• Failed - an error has occurred. Sponsored is false but it is set in the result type array.
• Failed - an error has occurred. The result types (result type 1, result type 2) does not exist.

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=project+name_top_sites_2021-03-15-2021-03-17_Google.com+Desktop+Universal_3690230fb8781295cafc4dfa254a544c"
}

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.

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 = projectName_top_sites_startDate-stopDate_searchEngine_uniqueHashCode
   • The file name parts are separated by an underscore
   • The two dates (older and newer one) separated by a dash
   • Use yyyy-mm-dd format
   • If startDate is equals to stopDate, only the startDate must be provided in the file name
   • The search engine is included in the export name only if the export is done for only one search engine provided by the user
   • The unique hash code is computed from the export inputs.
   • The unique hash code is included in the export name only if the export is done for at least one parameter excepting startDate and stopDate
   • _top_sites_ is a fixed value, if the export type is xlsx, _top_sites_xlsx_ is appended instead of _top_sites_

Example request

https://api.awrcloud.com/v2/get.php?action=get_topsites&token=myAPItoken&project=project+name&fileName=project+name_top_sites_2021-03-15-2021-03-17_Google.com+Desktop+Universal_3690230fb8781295cafc4dfa254a544c

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 gwt API call

This operation allows you to generate a Google Search Console export.

Limit: 150 calls per hour (shared with export ranking, export top sites and export visibility).

URL Parameters

1. action = gwt_export
2. token = token
   • The API token
3. project = project name
   • Use URL encoding and replace any space with a + sign
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. 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 Search Console metrics.

In addition to these cases, you might request a Google Search Console 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 search console 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 Search Console export.

URL Parameters

1. action = get_gwt
2. token = token
3. 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

1. action = visibility_export
2. project = project name
3. token = token
   • The API token
4. startDate = start date
   • The date to compare the exported metrics with
   • Use yyyy-mm-dd format
5. stopDate = stop date
   • The date for which to export the metrics
   • Use yyyy-mm-dd format
6. 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.
7. 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.
8. 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

This operation is used to download a previously scheduled visibility export. This operation uses the HTTP GET method.

URL Parameters

1. action = get_visibility
2. project = project name
   • Use URL encoding and replace any space with a + sign
3. token = token
   • The API token
4. 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 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
• ZIP archive not found. Please try again later.

The export landing pages API call (new)

This operation schedules a landing pages export for all dates in the startDate - stopDate interval and returns the link at which you'll find the zipped CSV file.

URL Parameters

1. action = export_pages
2. project = project name
3. token = token
   • The API token
4. startDate = start date
   • The first date in the range to export landing pages for
   • Use yyyy-mm-dd format
5. stopDate = stop date
   • The last date in the range to export landing pages for
   • Use yyyy-mm-dd format
6. searchengine = search engine (optional)
   • The search engine for which to export landing pages for - leave it blank to use the default (the first available search engine)
   • Use the search engine's ID. You can find the available search engines IDs for this project via the get details API call.
7. keywordgroup = keyword group (optional)
   • The keyword group for which to export landing pages for - leave it blank to use the default (all keywords)
   • Use the keyword group's name. You can find the available keyword groups for this project via the get details API call.
8. website = keyword group (optional)
   • The website for which to export landing pages for - leave it blank to use the default (the project's main website)
   • Use the website's name. You can find the available websites for this project via the get details API call.
9. encodeurl = encodeurl (optional)
   • Encodes the landing pages URLs - leave it blank to use the default (true)

Example request

https://api.awrcloud.com/v2/get.php?action=export_pages&project=project+name&token=myAPItoken&startDate=2013-07-23&stopDate=2013-12-27

Example response

If everything is OK, your download should start and look like this.

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_pages&token=myAPItoken&project=project+name&fileName=landingpages_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 - 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_pages&token=myAPItoken&project=project+name&fileName=landingpages_api-project name_2013-07-23-2013-12-27"
}

You can use the provided link to download it.

The get landing pages API call

This operation is used to download a previously scheduled landing pages export. This operation uses the HTTP GET method.

URL Parameters

1. action = get_pages
2. project = project name
   • Use URL encoding and replace any space with a + sign
3. token = token
   • The API token
4. fileName = landing pages_api-project name_startDate-stopDate-searchengine-keywordgroup-website
   • 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_pages&token=myAPItoken&fileName=landingpages_api_api-project_2015-07-01-2015-07-22

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

1. action = export_ctr
2. 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",
}

Example request

https://api.awrcloud.com/v2/get.php?action=export_ctr&token=myAPIToken&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

The get projects API call

This operation retrieves the full list of projects, with their ID and name.

Parameters

Can be included directly in the URL as GET parameters:

1. action = getProjects
2. token = API token

Example request

https://api.awrcloud.com/api/marketshare/v1/endpoint.php?action=getProjects&token=myAPItoken

Response

The output of a valid request like the one above is a JSON encoded list of projects.

[
  {
    "id": "1",
    "name": "my project 1"
  },
  {
    "id": "2",
    "name": "my project 2"
  }
]

Invalid responses

The output of an invalid request is also JSON encoded. You can recognize error responses by their errorCode key:

{
  "errorCode": 3,
  "message": "Failed - invalid token/action. Please specify a valid Developer API from your user account and a valid call from our API docs"
}

errorCode

If this is present, something went wrong and you should look at the message for details.

The get search engines API call

This operation retrieves the full list of search engines for a project, with their IDs and names, as displayed in the application.

Parameters

Can be included directly in the URL as GET parameters:

1. action = getSearchEngines
2. token = API token
3. projectId = project id
   • A project ID among the ones returned by getProjects

Example request

https://api.awrcloud.com/api/marketshare/v1/endpoint.php?action=getSearchEngines&token=myAPItoken&projectId=1

Response

The output of a valid request like the one above is a JSON encoded list of search engines.

[
  {
    "id": "-1",
    "name": "All search engines"
  },
  {
    "id": "5121",
    "name": "Google.com Desktop Universal"
  },
  {
    "id": "5104",
    "name": "Google.com Mobile Universal"
  }
]

Invalid responses

The output of an invalid request is also JSON encoded. You can recognize error responses by their errorCode key:

{
  "errorCode": 2,
  "message": "Failed - found missing project, you need to specify a valid one - use getProjects"
}

errorCode

If this is present, something went wrong and you should look at the message for details.

The get keyword groups API call

This operation retrieves the full list of keyword groups for a project, with their IDs and names.

Parameters

Can be included directly in the URL as GET parameters:

1. action = getKeywordGroups
2. token = API token
3. projectId = project id
   • A project ID among the ones returned by getProjects

Example request

https://api.awrcloud.com/api/marketshare/v1/endpoint.php?action=getKeywordGroups&token=myAPItoken&projectId=1

Response

The output of a valid request like the one above is a JSON encoded list of keyword groups.

[
  {
    "id": "-1",
    "name": "All keywords"
  },
  {
    "id": "1",
    "name": "My Keyword Group"
  }
]

Invalid responses

The output of an invalid request is also JSON encoded. You can recognize error responses by their errorCode key:

{
  "errorCode": 2,
  "message": "Failed - found missing project, you need to specify a valid one - use getProjects"
}

errorCode

If this is present, something went wrong and you should look at the message for details.

The get metadata API call

This operation retrieves metadata for the main website and its competitors, for one or multiple dates.

Parameters

Can be included directly in the URL as GET parameters:

1. action = getMetadata
2. token = API token
3. projectId = project id
   • A project ID among the ones returned by getProjects
4. searchEngineId = search engine id
   • -1 for All Search Engines or one from your project
5. keywordGroupId = keyword group id
   • -1 for All Keywords or one from your project
6. startDate = start date
   • The oldest date (inclusive)
   • Available after 2019-06-01
7. stopDate = stop date
   • The newest date (inclusive)
8. mode = download|plain (optional)
   • Whether to trigger a file download or return a plain text response

Example request

https://api.awrcloud.com/api/marketshare/v1/endpoint.php?action=getMetadata&token=myAPItoken&projectId=1&searchEngineId=-1&keywordGroupId=-1&startDate=2020-12-13&stopDate=2020-12-14

Response

The output of a valid request like the one above, targeting a project that's updated daily, is a CSV file that looks like this or a plain text response with the same contents:

date,keyword group id, keyword group,search engine id,search engine,domain,market share,urls,keywords,common keywords,unique keywords,competitor unique keywords,estimated visits,click share
2020-12-13,-1,All Keywords,-1,All Search Engines,allrecipes.com,21.94,494.00,185.00,0,185.00,0,12447085.37,6.53
2020-12-13,-1,All Keywords,-1,All Search Engines,wikipedia.org,7.20,115.00,68.00,65.00,120.00,3.00,4083576.06,13.24
...
2020-12-14,-1,All Keywords,-1,All Search Engines,allrecipes.com,20.91,499.00,183.00,0,183.00,0,11987953.30,6.37
2020-12-14,-1,All Keywords,-1,All Search Engines,wikipedia.org,7.14,113.00,69.00,65.00,118.00,4.00,4090449.77,13.93
...

Invalid responses

The output of an invalid request is JSON encoded. You can recognize error responses by their errorCode key:

{
  "errorCode": 2,
  "message": "Failed - found missing project, you need to specify a valid one - use getProjects"
}

errorCode

If this is present, something went wrong and you should look at the message for details.

The get domain keywords API call

This operation retrieves the keywords on which a domain was found on a specified date.

Parameters

Can be included directly in the URL as GET parameters:

1. action = getDomainKeywords
2. token = API token
3. projectId = project id
   • A project ID among the ones returned by getProjects
4. searchEngineId = search engine id
   • -1 for All Search Engines or one from your project
5. keywordGroupId = keyword group id
   • -1 for All Keywords or one from your project
6. date = date
   • A date among the ones returned by getMetadata
7. domain = domain
   • A domain among the ones returned by getMetadata - should be URL encoded
8. mode = download|plain (optional)
   • Whether to trigger a file download or return a plain text response

Example request

https://api.awrcloud.com/api/marketshare/v1/endpoint.php?action=getDomainKeywords&token=myAPItoken&projectId=1&searchEngineId=-1&keywordGroupId=-1&date=2020-12-13&domain=allrecipes.com

Response

The output of a valid request like the one above is a CSV file that looks like this or a plain text response with the same contents:

date,keyword group id,keyword group,search engine id,search engine,domain,keyword
2020-12-13,-1,All Keywords,-1,All Search Engines,allrecipes.com,stuffed green peppers
2020-12-13,-1,All Keywords,-1,All Search Engines,allrecipes.com,tarts
...

Invalid responses

The output of an invalid request is JSON encoded. You can recognize error responses by their errorCode key:

{
  "errorCode": 3,
  "message": "Failed - the domain appears to not exist in the dataset. Please use inputs offered by getMetadata"
}

errorCode

If this is present, something went wrong and you should look at the message for details.

The get domain URLs API call

This operation retrieves a domain's URLs found on SERPS from a specified date.

Parameters

Can be included directly in the URL as GET parameters:

1. action = getProjects
2. token = API token
3. projectId = project id
   • A project ID among the ones returned by getProjects
4. searchEngineId = search engine id
   • -1 for All Search Engines or one from your project
5. keywordGroupId = keyword group id
   • -1 for All Keywords or one from your project
6. date = date
   i A date among the ones returned by getMetadata and newer than 2020-10-04
7. domain = domain
   • A domain among the ones returned by getMetadata - should be URL encoded
8. mode = download|plain (optional)
   • Whether to trigger a file download or return a plain text response

Example request

https://api.awrcloud.com/api/marketshare/v1/endpoint.php?action=getDomainUrls&token=myAPItoken&projectId=1&searchEngineId=-1&keywordGroupId=-1&date=2020-12-13&domain=allrecipes.com

Response

The output of a valid request like the one above is a CSV file that looks like this or a plain text response with the same contents:

date,keyword group id,keyword group,search engine id,search engine,domain,url,market share,estimated visits,click share,keywords
2020-12-13,-1,All Keywords,-1,All Search Engines,allrecipes.com,https://www.allrecipes.com/,2.32,1318759.84,20.89,5
2020-12-13,-1,All Keywords,-1,All Search Engines,allrecipes.com,https://www.allrecipes.com/recipe/20144/banana-banana-bread/,1.60,906758.83,13.03,3
2020-12-13,-1,All Keywords,-1,All Search Engines,allrecipes.com,https://www.allrecipes.com/recipe/21014/good-old-fashioned-pancakes/,1.46,829136.61,17.21,3
...

Invalid responses

The output of an invalid request is JSON encoded. You can recognize error responses by their errorCode key:

{
  "errorCode": 3,
  "message": "Failed - the domain appears to not exist in the dataset. Please use inputs offered by getMetadata"
}

errorCode

If this is present, something went wrong and you should look at the message for details.

The get URL keywords API call

This operation retrieves the keywords for which an URL was ranking on a specified date.

Parameters

Can be included directly in the URL as GET parameters:

1. action = getProjects
2. token = API token
3. projectId = project id
   • A project ID among the ones returned by getProjects
4. searchEngineId = search engine id
   • -1 for All Search Engines or one from your project
5. keywordGroupId = keyword group id
   • -1 for All Keywords or one from your project
6. date = date
   • A date among the ones returned by getMetadata and newer than 2020-10-04
7. domain = domain
   • A domain among the ones returned by getMetadata - should be URL encoded
8. url = URL
   • An URL among the ones returned by getDomainUrls - should be URL encoded
   • Needs to belong to the domain above
   • Can be sent as a POST parameter to make sure the GET limit isn't exceeded
9. mode = download|plain (optional)
   • Whether to trigger a file download or return a plain text response

Example request

https://api.awrcloud.com/api/marketshare/v1/endpoint.php?action=getUrlKeywords&token=myAPItoken&projectId=1&searchEngineId=-1&keywordGroupId=-1&date=2020-12-13&domain=allrecipes.com&url=https://www.allrecipes.com/recipe/20144/banana-banana-bread/

Response

The output of a valid request like the one above is a CSV file that looks like this or a plain text response with the same contents:

date,keyword group id,keyword group,search engine id,search engine,domain,url,keyword
2020-12-13,-1,All Keywords,-1,All Search Engines,allrecipes.com,https://www.allrecipes.com/recipe/20144/banana-banana-bread/,banana bread recipe
2020-12-13,-1,All Keywords,-1,All Search Engines,allrecipes.com,https://www.allrecipes.com/recipe/20144/banana-banana-bread/,banana bread
...

Invalid responses

The output of an invalid request is JSON encoded. You can recognize error responses by their errorCode key:

{
  "errorCode": 3,
  "message": "Failed - the URL appears to not exist in the dataset. Please use inputs offered by getMetadata and getDomainUrls"
}

errorCode

If this is present, something went wrong and you should look at the message for details.