The Authoritas Platform: API Documentation

API Basics

The Authoritas API is divided into three sections:

Company functions
Site functions
System functions

Company functions are used by resellers to manage their customers’ companies. This includes adding new companies, and adding sites and users to those companies. These companies, users and sites are all visible in the Authoritas application.Site functions are used to manage sites which are not linked to any company in Authoritas. This means that these sites are not visible in the application, and can only be managed using the API.System functions provide information about the API.Your API key will allow access to various functions depending on your account type.

Accessing the API

The Authoritas API is accessed using an XML-RPC interface. To access the API, you will need an API key, which is tied to the domain which will be making the requests. Please contact us for your API key.

Request Format

Requests are submitted to the Authoritas XML-RPC server at http://app.authoritas.com/services/xmlrpc. Every method call requires four parameters to authenticate the request, followed by the method parameters.

Generation of these encryption parameters is described in more detail in authentication parameters.

Response Format

Every response has two sections: status and response.

Status contains a code, which is 1 for a successful request, or -1 for a failed request.

If the status code is -1, there will also be a status message describing the reason for the failed request.

The response section contains structured data which is specific to the requested method. A typical structured successful response to the system.getApiVersion method would be

status = Array
(
  code = 1
)
response = Array
(
  api_version = 1.0
)

For clarity, the returned data described for each method in section System Methods only shows the content of the “response” section. The API client code should check the status returned by the API method call before processing the response data.

Testing Your Encryption

To test if your authentication parameter generation is working correctly, try the following inputs:

domain = www.mydomain.com
api key = 1234567890abcdef1234567890abcdef
method = system.testMethod
timestamp = 1234567890
salt = abcdefgh1234

Your parameter generation function should generate the string
07f295d383d37658300ee330ee715e4d422a0a513c675636028369a8fdcb7eda

Usage Limits

There are limits associated with each api key.Limits are imposed on:

The number of keywords that can be ranked per API call, where relevant.
The number of pages that are Spidered for sites added through the API.
The number of back-links that can be fetched for sites added through the API.

System Methods

These methods are used to access data about the Authoritas system.

system.getVersion

This method gets the current version of the API. This can be used to check that the API documentation is for the correct version of the API.

Request parameters

Parameter Name	Type	Description
hash	string	Cryptographic hash data – see authentication parameters
domain	string	Requesting domain – see authentication parameters
timestamp	string	Request timestamp – see authentication parameters
salt	string	Cryptographic salt – see authentication parameters

Response data

Parameter Name	Type	Description
api_version	string	The version number of the API

Company Methods

These methods are used to create, query and modify data about companies on the Authoritas system. Users and sites all belong to companies.

company.addResellerClient

This method adds a new company to the Authoritas system as a child company of a reseller, and creates an admin user for the new company. If the company is added successfully, the Authoritas ID of the new company is returned. This ID should be stored and used for subsequent operations on that company.

Request parameters

Parameter Name	Type	Description
hash	string	Cryptographic hash data – see authentication parameters
domain	string	Requesting domain – see authentication parameters
timestamp	string	Request timestamp – see authentication parameters
salt	string	Cryptographic salt – see authentication parameters
company_name	string	Name for the new company
email	string	Email address for the new admin user
password	string	Password for the new admin user
package	string	Pricing package for the new company

Response data

Parameter Name	Type	Description
company_id	int	The unique ID for this company on Authoritas

Note that all reseller client companies must have a pricing package. These packages will have been set up for you by Authoritas.

company.updateResellerClient

This method allows resellers to update details of one of their reseller client companies.

Request parameters

Parameter Name	Type	Description
hash	string	Cryptographic hash data – see authentication parameters
domain	string	Requesting domain – see authentication parameters
timestamp	string	Request timestamp – see authentication parameters
salt	string	Cryptographic salt – see authentication parameters
company_id	int	Company ID of the company to be updated
company_details	string	JSON-encoded array of data to be updated. Currently supported keys are “name” (to upate the company name) and “package” (to update the pricing package of the company)

Response data

There is no response data from this function call. Note that success or failure is indicated in a different part of the response message from the response data.

company.getResellerClients

This method gets a list of all the companies which are managed by the current partner.

Request parameters

Parameter Name	Type	Description
hash	string	Cryptographic hash data – see authentication parameters
domain	string	Requesting domain – see authentication parameters
timestamp	string	Request timestamp – see authentication parameters
salt	string	Cryptographic salt – see authentication parameters

Response data

Parameter Name	Type	Description
companies	array	An array of companies

Company data format:

Parameter Name	Type	Description
company_id	int	The unique ID of the company
name	string	The name of the company

company.addSite

This method adds a new site to a company.

Request parameters

Parameter Name

Type

Description

hash

string

Cryptographic hash data – see authentication parameters

domain

string

Requesting domain – see authentication parameters

timestamp

string

Request timestamp – see authentication parameters

salt

string

Cryptographic salt – see authentication parameters

company_id

optional

The ID of the company to add the new site to. If not supplied or set to zero, the new site will be added to the company associated with the requesting API key.

url

string

The URL of the new site

name

string

The name of the web site

target_market

string

The market this web site is targetting. See target markets

primary_search_engine

string

The primary search engine to check keyword ranks on. See search engines. Additional search engines can be specified in the optional site parameters.

JSON_options

string

Optional JSON-formatted string with additional settings for the new site.

Parameter Name	Type	Description
location	string	The location served by this business. Used to check local directory listings.
search_engine_2	string	Second search engine to check keyword ranks on. See search engines
search_engine_3	string	Third search engine to check keyword ranks on. See search engines
search_engine_4	string	Fourth search engine to check keyword ranks on. See search engines
competitor_1	string	URL of first competitor site
competitor_2	string	URL of second competitor site
competitor_3	string	URL of third competitor site
competitor_4	string	URL of fourth competitor site
competitor_5	string	URL of fifth competitor site
campaign_name	string	Name for the initial campaign for this site
campaign_description	string	Description for the initial campaign for this site
campaign_start_date	string	Start date for the initial campaign in ISO date format (yyyy-mm-dd). Defaults to the current date if not supplied.
campaign_end_date	string	End date for the initial campaign in ISO date format (yyyy-mm-dd). Defaults to one year from the current date if not supplied.
max_crawled_pages	int	Maximum number of pages to crawl on this site. Defaults to 5000 if not specified.
max_inbound_links	int	Maximum number of inbound links to check for this site. Defaults to 5000 if not specified.
keyword_group_1	string	Name of the first group of keywords
keywords_1	array	Array of keywords to add to keyword group 1
keyword_group_2	string	Name of the second group of keywords
keywords_2	array	Array of keywords to add to keyword group 2
…	…	…
keyword_group_15	string	Name of the fifteenth group of keywords
keywords_15	array	Array of keywords to add to keyword group 15

Response data

Parameter Name	Type	Description
site_id	int	The unique ID for this site on Authoritas

company.getSites

This method gets a list of all the sites this company is currently managing on Authoritas.

Request parameters

Parameter Name	Type	Description
hash	string	Cryptographic hash data – see authentication parameters
domain	string	Requesting domain – see authentication parameters
timestamp	string	Request timestamp – see authentication parameters
salt	string	Cryptographic salt – see authentication parameters
company_id	int	Optional. The ID of the company to be checked. If not supplied (or zero), this will return the sites which belong to the company associated with the requesting API key.

Response data

Parameter Name	Type	Description
sites	array	An array of sites currently managed by this company

Site data format:

Parameter Name	Type	Description
site_id	int	Unique ID of the site
url	string	The URL of the site
last_spider_date	int	Unix timestamp showing when this site was last crawled
last_inbound_links_date	int	Unix timestamp showing when inbound links were last updated for this site
last_keyword_ranks_date	int	Unix timestamp showing when keyword ranks were last checked for this site
campaigns	array	Array of campaigns associated with this site

Campaign data format:

Parameter Name	Type	Description
campaign ID	int	Unique ID of the campaign
name	string	The name of the campaign

company.addAffiliate

This method adds a new affiliate account to the Authoritas system. This is designed for use with the howgoodisyourseo.com lead generation tool, and will allow the affiliate to send site.instantAudit requests from their own branded version using their own API key.

Request parameters

Parameter Name	Type	Description
hash	string	Cryptographic hash data – see authentication parameters
domain	string	Requesting domain – see authentication parameters
timestamp	string	Request timestamp – see authentication parameters
salt	string	Cryptographic salt – see authentication parameters
company_name	string	The name of the affiliate company
email_address	string	The email address of the new affiliate user
domain	string	The domain the site.instantAudit API requests will originate from

Response data

Parameter Name	Type	Description
uid	int	The user ID for the new affiliate user. This should be used when referring traffic to Authoritas in order to attribute the visit to the correct affiliate.
api_key	string	The API key for the new affiliate account.

company.addUser

This method adds a new user to the Authoritas system. If the user is added successfully, their login password will be returned. Authoritas will not notify the user of these account details – it is the responsibility of the API implementor to inform the user of their new password.

Request parameters

Parameter Name	Type	Description
hash	string	Cryptographic hash data – see authentication parameters
domain	string	Requesting domain – see authentication parameters
timestamp	string	Request timestamp – see authentication parameters
salt	string	Cryptographic salt – see authentication parameters
company_id	int	The unique ID of the company this user will belong to
email_address	string	The email address of the user to be added
language	string	The two-character ISO code of the default language for the new user. See ISO Language Codes for valid language codes.

Response data

Parameter Name	Type	Description
password	string	The password for this user to log in to Authoritas

company.getUsers

This method gets a list of all user accounts belonging to the specified company.

Request parameters

Parameter Name	Type	Description
hash	string	Cryptographic hash data – see authentication parameters
domain	string	Requesting domain – see authentication parameters
timestamp	string	Request timestamp – see authentication parameters
salt	string	Cryptographic salt – see authentication parameters
company_id	int	The ID of the company to be checked

Response data

Parameter Name	Type	Description
users	array	An array of users belonging to this company

User data format:

Parameter Name	Type	Description
user_id	int	Unique ID of the user
email_address	string	The email address of this user

Site Methods

These methods perform operations at the site level. These are used to manage sites which do not belong to a company. This means that sites managed using these functions are not visible in the Authoritas user interface – their data is only accessible using these API functions.

site.instantAudit

This function performs an instant audit on the specified site using a sample search phrase to
check the rank for this site and the competitors for this search phrase.

Request parameters

Parameter Name

Type

Description

hash

string

Cryptographic hash data – see authentication parameters

domain

string

Requesting domain – see authentication parameters

timestamp

string

Request timestamp – see authentication parameters

salt

string

Cryptographic salt – see authentication parameters

url

string

The URL of the site to be analysed

keyword

string

The main search phrase for this site

competitor1

string

The URL of the first competitor. An empty string will result in a ‘guessed’ competitor based on other domains in search results for the specified keyword

competitor2

string

The URL of the second competitor. An empty string will result in a ‘guessed’ competitor based on other domains in search results for the specified keyword

JSON_options

string

An optional JSON formatted string with additional options.The supported parameters are:

JSON Parameters
Parameter Name	Type	Default	Description
country	string	gb	Country code
region	string	<empty>	Region for Yahoo local
business	string	<empty>	Business name for Yahoo local
noAutoCompetitor	boolean	false	Switch off automatically ‘guessing’ 2 competitors and just return data for the specified url
maxResults	int	20	The maximum number of ranks to check for keyword rankings. Larger values will take longer to return data.

For example to change the country code to the USA; look for a business called Microsoft in the Seattle region in local Yahoo searches; and switch off fetch competitors, Use the following JSON string for this parameter.

‘ {“country” : “us”,

“region” : “seattle”,

“business” : “microsoft “,

“noAutoCompetitor” : true

} ‘

Changing the country code affects the search engine used for keyword rankings.

Response data

Parameter Name	Type	Description
audit_results	array	The results of the audit

Sample response:

audit_results
  main_site
    url = www.someurl.com
    keyword_rank_google = 1
    result_type = organic
    pages_indexed_google = 279
    pages_indexed_bing = 154
    local_in_google = 0
    local_in_yahoo = 0
    local_in_bing = 1
    inbound_links = 30
    referring_domains = 5
    robots_exists = TRUE
    sitemap_xml = TRUE
    sitemap_html = FALSE
    has_canonical = TRUE
    homepage_load_time = 287
    keyword_in_title = TRUE
    analysis_package = Omniture
    has_twitter_link = TRUE
    twitter_user = tweetWithUs
    twitter_follower_count = 42
    has_facebook_like = TRUE
    facebook_like_count = 1950
    has_google_plusone = TRUE
    google_plusone_count = 560
    scores
      content = 88
      keywords = 76
      popularity = 46
      technical = 94
competitor1
    url = www.somecompetitor.com
    keyword_rank_google = 4
    result_type = organic
    pagerank = 9
    pages_indexed_google = 2179
    pages_indexed_bing = 144
    local_in_google = 1
    local_in_yahoo = 1
    local_in_bing = 1
    inbound_links = 40
    referring_domains = 15
    robots_exists = TRUE
    sitemap_xml = TRUE
    sitemap_html = FALSE
    has_canonical = TRUE
    homepage_load_time = 287
    keyword_in_title = TRUE
    analysis_package = Google Analytics
    has_twitter_link = FALSE
    twitter_user = -1
    twitter_follower_count = 0
    has_facebook_like = TRUE
    facebook_like_count = 19
    has_google_plusone = TRUE
    google_plusone_count = 5
    scores
      content = 75
      keywords = 56
      popularity = 40
      technical = 99
competitor2
    url = www.competitor2.com
    ...
    ...
    ... 
    has_twitter_link = FALSE
    twitter_user = tweetbetter
    twitter_follow_count = 99

site.suggestKeywords

This function will suggest keywords for a site by analysing the home page of the web site and the home page of any competitors which have been set for this site, or analysing all the crawled pages if we have crawled the sites.

Request parameters

Parameter Name	Type	Description
hash	string	Cryptographic hash data – see authentication parameters
domain	string	Requesting domain – see authentication parameters
timestamp	string	Request timestamp – see authentication parameters
salt	string	Cryptographic salt – see authentication parameters
url	string	The url of the site to be analysed

Response data

Parameter Name	Type	Description
keywords	array	An array of the top 25 keywords sorted by frequency

Sample response:

keywords
  drupal
  website development
  jquery

site.suggestCompetitors

This function will suggest competitors for a site by analysing the home page of the web site and the home page of any competitors which have been set for this site.

The competitors are found by searching www.google.co.uk (or a local google if the country code is changed) for the specified keyword and returning all organic and Google Places results (excluding the site being analysed) found on the first page.

Request parameters

Parameter Name	Type	Description
hash	string	Cryptographic hash data – see authentication parameters
domain	string	Requesting domain – see authentication parameters
timestamp	string	Request timestamp – see authentication parameters
salt	string	Cryptographic salt – see authentication parameters
url	string	The url of the site to be analysed
keyword	string	The keyword to suggest competitors on
country	string	Optional. This is a country code used to determine the search engine to use when looking for competitors.The default is ‘gb’.

Response data

Parameter Name	Type	Description
competitors	array	An array of suggested competitors

Sample response:

competitors
  competitor
    url = www.competitor1.com
    result_type = organic
  competitor
    url = www.competitor2.com
    result_type = organic
  competitor
    url = www.competitor3.com
    result_type = places
  competitor
    url = www.competitor4.com
    result_type = places
  competitor
    url = www.competitor5.com
    result_type = places

site.updateKeywords

This function will update the keywords for a specific campaign on a site.

Request parameters

Parameter Name	Type	Description
hash	string	Cryptographic hash data – see authentication parameters
domain	string	Requesting domain – see authentication parameters
timestamp	string	Request timestamp – see authentication parameters
salt	string	Cryptographic salt – see authentication parameters
url	string	The url of the site to be added or updated
campaign_id	int	The campaign ID to modify keywords on
keyword_group	string	Optional. The name of the keyword group these keywords belong to. If not supplied or blank, this will default to “api”
keywords	array	An array of keywords
monitor	bool	Should the passed keywords be monitored
operation	string	“add”, “update” or “delete”

Response data

There is no response data from this function call. Note that success or failure is indicated in a different part of the response message from the response data.

site.updateSite

This function will update a site, or add it if it doesn’t already exist on the database. If the site is being updated, the existing keywords and competitors will be completely replaced by the keywords and competitors in the request if they are set. If either is not set, that data will not be modified at all.

Request parameters

Parameter Name

Type

Description

hash

string

Cryptographic hash data – see authentication parameters

domain

string

Requesting domain – see authentication parameters

timestamp

string

Request timestamp – see authentication parameters

salt

string

Cryptographic salt – see authentication parameters

url

string

The url of the site to be added or updated

competitors

array

An array of up to 5 competitor URLs

keywords

array

An array of up to 10 keywords

monitor_site

boolean

Indicate whether to continue monitoring this site. Used to
disable monitoring for a site if they cancel their account.

JSON_options

string

An optional JSON formatted string with additional options.The supportted parameters are:

Parameter Name	Type	Default	Description
country	string	gb	Country code

For example to change the country code to the USA pass the string

‘ {“country” : “us”} ‘

Changing the country code affects the serach engine used for keyword rankings

Response data

There is no response data from this function call. Note that success or failure is indicated in a different part of the response message from the response data.

site.getSiteData

This function will return all the data we have about a site.

Request parameters

Parameter Name

Type

Description

hash

string

Cryptographic hash data – see authentication parameters

domain

string

Requesting domain – see authentication parameters

timestamp

string

Request timestamp – see authentication parameters

salt

string

Cryptographic salt – see authentication parameters

url

string

The url of the site to be reported on

previous_date

int

The date of the previous GetSiteData request. This date will be used to calculate new and lost links. The date should be in ISO date format (yyyy-mm-dd).

campaign_id

int

The campaign ID to be reported on. Optional – if not supplied (or zero) this will default to the first campaign on the site.

data_date

int

Optional. Date to get data for, in ISO date format (yyyy-mm-dd). Each type of data will be returned for the first date after this date for which that data is available. If this is not set, the most recent data for each type will be returned.

data_limits

string

JSON-formatted array of optional parameters to limit the number of results returned of each data type. These can be set to -1 to return all data of that type, 0 to return no data of that type, or a number to return that number of rows of data of that type.

Parameter Name	Type	Default	Description
basic_data	int	-1	Basic technical data about site
new_links	int	50	New links to this site since previous_date
lost_links	int	50	Links lost since previous_date
inbound_links	int	10	Current inbound links to this site, sorted by link quality
broken_links	int	-1	Dead links found on this site when we crawled it
page_meta_data	int	-1	Pages with missing, short or long meta-data found on this site when we crawled it
keyword_ranks	int	10	Keyword ranks
keyword_groups	int	0	Keyword groups containing keywords on this campaign
competitors	int	-1	Data collected for competitors. Note that this will also be subject to the other data limits where applicable.

Response data

Parameter Name	Type	Description
site_data	array	An array of data about the site and their competitors

If the data is not yet ready for this site, or the requested URL does not exist on Authoritas, a standard error response will be returned with an error message indicating the cause of the error.
Sample response:

customer
  url
  basic_data_last_updated
  link_data_last_updated
  crawl_data_last_updated
  keyword_rank_data_last_updated
  homepage_load_time
  pagerank
  pages_indexed_google
  new_link_count
  new_links
    link
      source_page
      target_page
      anchor_text
    link
      source_page
      target_page
      anchor_text
  lost_link_count
  lost_links
    link
      source_page
      target_page
      anchor_text
    link
      source_page
      target_page
      anchor_text
  inbound_link_count
  inbound_links
    link
      source_page
      target_page
      anchor_text
    link
      source_page
      target_page
      anchor_text
  broken_link_count
  broken_links
    link
      source_page
      target_page
    link
      source_page
      target_page
  missing_page_title_count
  missing_page_titles
    page_url
    page_url
  duplicate_page_title_count
  duplicate_page_titles
    title
      page_url
      page_url
    title
      page_url
      page_url
  missing_page_description_count
  missing_page_descriptions
    page_url
    page_url
  duplicate_page_description_count
  duplicate_page_descriptions
    description
      page_url
      page_url
    description
      page_url
      page_url
  keyword groups
    group1
    group2
    group3
  keyword_rankings
    keyword
      1
        search_engine
        rank
      2
        search_engine
        rank
      3
        search_engine
        rank
      4
        search_engine
        rank
    keyword
      1
        search_engine
        rank
      2
        search_engine
        rank
      3
        search_engine
        rank
      4
        search_engine
        rank
    keyword
      1
        search_engine
        rank
      2
        search_engine
        rank
      3
        search_engine
        rank
      4
        search_engine
        rank
competitor1
  url
  homepage_load_time
  pagerank
  pages_indexed_google
  new_link_count
  new_links
    link
      source_page
      target_page
      anchor_text
    link
      source_page
      target_page
      anchor_text
  lost_link_count
  inbound_link_count
  inbound_links
    link
      source_page
      target_page
      anchor_text
    link
      source_page
      target_page
      anchor_text

Keyword ranks are reported as follows:

1 – 100: the organic rank of the keyword in that search engine
9999: the keyword is unranked in that search engine
-1: we were unable to get a consistent rank for that keyword in that search engine

site.getOrganicKeywordsRankingByPeriod

This function will retrieve from our database all organic keywords ranking (for all search engines setup) for the given site, campaign and period

Request parameters

Parameter Name	Type	Description
hash	string	Cryptographic hash data – see authentication parameters
domain	string	Requesting domain – see authentication parameters
timestamp	string	Request timestamp – see authentication parameters
salt	string	Cryptographic salt – see authentication parameters
site_id	integer	The id of the desired site in our database
campaign_id	integer	The id of the desired campaign in our database
period	string	The desired period (1day, 7days, 30days, lastmonth, 3months, 6months, 2016, 2015, wholecampaign)
domain_alias	boolean	Active or disabled domain alias functionality. (This is only available for enterprise packages)
offset	integer	The offset of the keywords ranking in our database
limit	integer	Limit the number of returned keywords (max. value is 350)

Response data

Parameter Name	Type	Description
organic	array	An array of data containing organic ranking and ranks

Maximum value for parameter “limit” is set to 350. To query more than350 keywords you have to use the “offset” parameter and use multiple queries.

Sample response:

reponse
 site_id
 campaign_id
 offset
 limit
 total_count
 total_keywords
 date
 organic
  keywords
   0
    keyword
    keyword_id
    url
    0 
     url
     domain_alias  
     ranking
      0
       domain
       engine_ui_order
       region
         id
         code
         display_name
         tld
         town
           id
           display_name
         start_rank
         final_rank
         best_rank
         ranking_date
           start 
           final 
         device
           id 
           internal_name
           display_name
         language
           id
           code
           display_name
...

JSON example:
{
   "response": {
   "total_count": 5,
   "limit": 5,
   "offset": 0,
   "campaign_id": 1,
   "period": "7days",
   "organic": {
     "keywords": [
     {
       "keyword_id": 1234,
       "url": [
       {
         "ranking": [
         {
           "domain": "www.test.com",
           "engine_ui_order": "1",
           "region": {
             "id": 1,
             "code": "us",
             "town": {
               "id": 0,
               "display_name": ""
             },
             "display_name": "usa",
             "tld": ".com"
           },
         "start_rank": 1,
         "rank_change": 0,
         "search_engine": {
           "id": 1,
           "internal_name": "google",
           "display_name": "Google"
         },
         "final_rank": 1,
         "ranking_date": {
         "start": "2016-06-25 01:00:00",
         "final": "2016-07-01 11:46:47"
      },
      "search_type": "web",
      "best_rank": 1,
      "device": {
        "id": 3,
        "internal_name": "pc",
        "display_name": "PC - Windows - Chrome"
      },
      "language": {
        "id": 1,
        "code": "en",
        "display_name": "English"
     }
 },

site.getOrganicKeywordsRankingByDate

This function will retrieve from our database all organic keywords ranking (for all search engines setup) for the given site, campaign and date

Request parameters

Parameter Name	Type	Description
hash	string	Cryptographic hash data – see authentication parameters
domain	string	Requesting domain – see authentication parameters
timestamp	string	Request timestamp – see authentication parameters
salt	string	Cryptographic salt – see authentication parameters
site_id	integer	The id of the desired site in our database
campaign_id	integer	The id of the desired campaign in our database
date	string	The desired date (format yyyy-mm-dd)
domain_alias	boolean	Active or disabled domain alias functionality. (This is only available for enterprise packages)
offset	integer	The offset of the keywords ranking in our database
limit	integer	Limit the number of returned keywords (max. value is 350)
competitive	boolean	Show competitor’s data

Response data

Parameter Name	Type	Description
organic	array	An array of data containing organic ranking and ranks

Maximum value for parameter “limit” is set to 350. To query more than350 keywords you have to use the “offset” parameter and use multiple queries.

Sample response:

reponse
 site_id
 campaign_id
 offset
 limit
 total_count
 total_keywords
 date
 organic
  0
   keyword
   keyword_id
   search_volume
   keyword_tags
   primary_keyword_group
   sites
    0   
     ranking
      0
       search_type
       rank
       domain_alias
       device
         id
         name
         internal
       region
         id
         country
         code
         town
         name
         tld
       language
         id
         code
         name
       search_engine
         id
         name 
         internal

...

JSON example:

{
   "response": {
   "total_count": 1,
   "limit": 1,
   "offset": 0,
   "campaign_id": 1234,
   "date": "2016-06-10",
   "site_id": 1234,
   "total_keywords": 6000,
   "organic": [
   {
     "sites": [
     {
       "competitor": false,
       "site_url": "http://www.mysite.com/",
       "site_id": 1234
       "ranking": [
       {
         "search_engine": {
         "id": "1",
         "name": "Google",
         "internal": "google"
       },
       "language": {
         "id": "1",
         "code": "en",
         "name": "English"
       },
       "region": {
         "id": "1",
         "country": "usa",
         "code": "us",
         "town": "",
         "name": "United States",
        "tld": ".com"
       },
       "page": "1",
       "search_type": "web",
       "landing_page": "http://mysite.com/abcd",
       "device": {
       "id": "2",
       "name": "iPhone - iOS - Safari",
       "internal": "iphone"
     },
     "rank": "1",
     "domain_alias": 0
    },
    ],
 },
},
...

site.getUniversalKeywordsRanking

This function will retrieve from our database all universal keywords ranking for the given site and campaign.

Request parameters

Parameter Name	Type	Description
hash	string	Cryptographic hash data – see authentication parameters
domain	string	Requesting domain – see authentication parameters
timestamp	string	Request timestamp – see authentication parameters
salt	string	Cryptographic salt – see authentication parameters
site_id	integer	The id of the desired site in our database
campaign_id	integer	The id of the desired campaign in our database
offset	integer	The offset of the keywords ranking in our database
limit	integer	Limit the number of returned keywords (max. value is 2,000)

Response data

Parameter Name	Type	Description
organic	array	An array of data containing organic ranking and ranks

Maximum value for parameter “limit” is set to 2,000. To query more than 2,000 keywords you have to use the “offset” parameter and use multiple queries.

Example for 10,000 keywords:

1st query: offset: 0, limit 2,000
2nd query: offset: 2,001, limit 4,000
3rd query: offset: 4,001, limit 6,000
4th query: offset: 6,001, limit 8,000
5th query: offset: 8,001, limit 10,000

Sample response:

reponse
  site_id
  campaign_id
  offset
  limit
  total_count
  total_keywords
  universal
    0
      keyword
      keyword_id
      organic_rank
      universal_rank
      universal_rank_change
      video_rank
      place_rank
      image_rank
      direct_answer_rank
      result_order
      date
...

JSON Example:

{
 "response": {
   "total_count": 1,
   "total_keywords": 1,
   "offset": 0,
   "limit": 2000,
   "site_id": 123456,
   "campaign_id": 123456,
   "universal": [
   {
     "image_rank": "-1",
     "universal_page": "1",
     "organic_rank": "5",
     "universal_rank_change": "0",
     "date": "1457913600",
     "universal_rank": "1",
     "direct_answer_rank": "1",
     "results_order": "a:3:{i:1;a:2:{s:4:"type";s:5:"place";s:5:"count";i:3;}i:2;a:2:{s:4:"type";s:7:"organic";s:5:"count";i:10;}i:3;a:2:{s:4:"type";s:13:"direct_answer";s:5:"count";i:1;}}",
     "video_rank": "0",
     "keyword": "test",
     "keyword_id": "123456",
     "places_rank": "1"
   }
 ],
 },
 "status": {
 "code": 1
 }
}
...

site.getKeywordsGroups

This function will retrieve from our database all the keywords groups defined for a specific site and campaign

Request parameters

Parameter Name	Type	Description
hash	string	Cryptographic hash data – see authentication parameters
domain	string	Requesting domain – see authentication parameters
timestamp	string	Request timestamp – see authentication parameters
salt	string	Cryptographic salt – see authentication parameters
site_id	integer	The id of the desired site in our database
campaign_id	integer	The id of the desired campaign in our database

Response data

Parameter Name	Type	Description
keywords_groups	array	An array of data containing keywords groups

Sample response:

reponse
 site_id
 campaign_id 
 total_count
 keywords_groups
  0
    group_name
    group_id
1
    group_name
    group_id
...

JSON example:

{
 "response": {
  "total_count": 13,
  "site_id": 1,
  "campaign_id": 2,
  "keywords_groups": [
    {
      "group_name": "Analytics",
      "group_id": 14
    },
    {
      "group_name": "SEO",
      "group_id": 15
    },
...

site.getCategories

This function will retrieve from our database all the categories defined for a specific site and campaign

Request parameters

Parameter Name	Type	Description
hash	string	Cryptographic hash data – see authentication parameters
domain	string	Requesting domain – see authentication parameters
timestamp	string	Request timestamp – see authentication parameters
salt	string	Cryptographic salt – see authentication parameters
site_id	integer	The id of the desired site in our database
campaign_id	integer	The id of the desired campaign in our database

Response data

Parameter Name	Type	Description
categories	array	An array of data containing categories

Sample response:

reponse
 site_id
 campaign_id 
 total_count
 categories
  0
    category_id
    category_name
  1
    category_id
    category_name
...

JSON example:

{
"response": {
  "site_id": 1,
  "campaign_id": 2,
  "total_count": 13,
  "categories": [
    {
      "category_name": "Analytics",
      "category_id": 14
    },
    {
      "category_name": "SEO",
      "category_id": 15
    },
...

site.getMarketVisibility

This function will retrieve from our database all the market visibility data available for a specific site ,campaign and date

Request parameters

Parameter Name	Type	Description
hash	string	Cryptographic hash data – see authentication parameters
domain	string	Requesting domain – see authentication parameters
timestamp	string	Request timestamp – see authentication parameters
salt	string	Cryptographic salt – see authentication parameters
site_id	integer	The id of the desired site in our database
campaign_id	integer	The id of the desired campaign in our database
date	string	The desired date (format yyyy-mm-dd)
keyword_group_id	integer	The id of the desired keyword group (-1: All keywords groups, 0: Un-grouped)
category_id	integer	The id of the desired category (-1: All categories)

Response data

Parameter Name	Type	Description
market_visibility	array	An array of data containing market visibiltity

Sample response:

reponse
 site_id
 campaign_id 
 total_count
 keyword_group_id
 category_id
 market_visibility
  total
   market_visibility
  data
   0
    domain_id
    domain
    market_visibility
    market_visibility_share
   1
    domain_id
    domain
    market_visibility
    market_visibility_share
...

JSON example:

{
 "response": {
   "total_count": 10,
   "category_id": -1,
   "campaign_id": 37,
   "keyword_group_id": -1,
   "date": "2016-06-12",
   "site_id": 123,
   "market_visibility": {
   "data": [
   {
     "domain": "www.test.net",
     "market_visibility_share": 33.93,
     "market_visibility": 399246.92,
     "domain_id": "123"
  },
  {
     "domain": "www.test-two.org",
     "market_visibility_share": 14.69,
     "market_visibility": 172852.26,
     "domain_id": "1234"
  },
...

ISO Language Codes

The currently supported languages codes are:

en	English (UK)
he	Hebrew
nb	Norwegian (Bokmal)
sv	Swedish
fr	French
en-US	US English

Markets

These are the markets which can be set as the default market for new sites:

Global
Algeria
Argentina
Australia
Austria
Azerbaijan
Bangladesh
Belgium
Botswana
Brazil
Bulgaria
Canada
Chile
China
Colombia
Croatia
Czech Republic
Denmark
Ecuador
Egypt
Finland
France
Germany
Gibraltar
Greece
Hong Kong
Hungary
India
Indonesia
Ireland
Israel
Italy
Japan
Kenya
Kuwait
Luxembourg
Malaysia
Mexico
Morocco
Netherlands
New Zealand
Nigeria
Norway
Pakistan
Peru
Philippines
Poland
Portugal
Qatar
Romania
Russia
Saudi Arabia
Serbia
Singapore
Slovakia
Slovenia
South Africa
South Korea
Spain
Sri Lanka
Sweden
Switzerland
Taiwan
Thailand
Turkey
Ukraine
United Arab Emirates
United Kingdom
United States
Venezuela
Vietnam

Search Engines

These are the search engines whcih can be set for a site:

Google Global
Google Algeria Whole Web
Google Algeria Pages From Algeria
Google Argentina Whole Web
Google Argentina Pages From Argentina
Google Australia Whole Web
Google Australia Pages From Australia
Google Austria Whole Web
Google Austria Pages From Austria
Google Azerbaijan Whole Web
Google Bangladesh Whole Web
Google Bangladesh Pages From Bangladesh
Google Belgium Whole Web
Google Belgium Pages From Belgium
Google Botswana Whole Web
Google Botswana Pages From Botswana
Google Brazil Whole Web
Google Brazil Pages From Brazil
Google Bulgaria Whole Web
Google Bulgaria Pages From Bulgaria
Google Canada Whole Web
Google Canada Pages From Canada
Google Chile Whole Web
Google Chile Pages From Chile
Google China Whole Web
Google Colombia Whole Web
Google Colombia Pages From Colombia
Google Croatia Whole Web
Google Croatia Pages From Croatia
Google Czech Republic Whole Web
Google Czech Republic Pages From Czech Republic
Google Denmark Whole Web
Google Denmark Pages From Denmark
Google Ecuador Whole Web
Google Ecuador Pages From Ecuador
Google Egypt Whole Web
Google Egypt Pages From Egypt
Google Finland Whole Web
Google Finland Pages From Finland
Google France Whole Web
Google France Pages From France
Google Germany Whole Web
Google Germany Pages From Germany
Google Gibraltar Whole Web
Google Greece Whole Web
Google Greece Pages From Greece
Google Hong Kong Whole Web
Google Hong Kong Pages From Hong Kong
Google Hungary Whole Web
Google Hungary Pages From Hungary
Google India Whole Web
Google India Pages From India
Google Indonesia Whole Web
Google Indonesia Pages From Indonesia
Google Ireland Whole Web
Google Ireland Pages From Ireland
Google Israel Whole Web
Google Israel Pages From Israel
Google Italy Whole Web
Google Italy Pages From Italy
Google Japan Whole Web
Google Japan Pages From Japan
Google Kenya Whole Web
Google Kenya Pages From Kenya
Google Kuwait Whole Web
Google Kuwait Pages From Kuwait
Google Luxembourg Whole Web
Google Luxembourg Pages From Luxembourg
Google Malaysia Whole Web
Google Malaysia Pages From Malaysia
Google Mexico Whole Web
Google Mexico Pages From Mexico
Google Morocco Whole Web
Google Morocco Pages From Morocco
Google Netherlands Whole Web
Google Netherlands Pages From Netherlands
Google New Zealand Whole Web
Google New Zealand Pages From New Zealand
Google Nigeria Whole Web
Google Nigeria Pages From Nigeria
Google Norway Whole Web
Google Norway Pages From Norway
Google Pakistan Whole Web
Google Pakistan Pages From Pakistan
Google Peru Whole Web
Google Peru Pages From Peru
Google Philippines Whole Web
Google Philippines Pages From Philippines
Google Poland Whole Web
Google Poland Pages From Poland
Google Portugal Whole Web
Google Portugal Pages From Portugal
Google Qatar Whole Web
Google Qatar Pages From Qatar
Google Romania Whole Web
Google Romania Pages From Romania
Google Russia Whole Web
Google Russia Pages From Russia
Google Saudi Arabia Whole Web
Google Saudi Arabia Pages From Saudi Arabia
Google Serbia Whole Web
Google Serbia Pages From Serbia
Google Singapore Whole Web
Google Singapore Pages From Singapore
Google Slovakia Whole Web
Google Slovakia Pages From Slovakia
Google Slovenia Whole Web
Google Slovenia Pages From Slovenia
Google South Africa Whole Web
Google South Africa Pages From South Africa
Google South Korea Whole Web
Google South Korea Pages From South Korea
Google Spain Whole Web
Google Spain Pages From Spain
Google Sri Lanka Whole Web
Google Sri Lanka Pages From Sri Lanka
Google Sweden Whole Web
Google Sweden Pages From Sweden
Google Switzerland Whole Web
Google Switzerland Pages From Switzerland
Google Taiwan Whole Web
Google Taiwan Pages From Taiwan
Google Thailand Whole Web
Google Thailand Pages From Thailand
Google Turkey Whole Web
Google Turkey Pages From Turkey
Google Ukraine Whole Web
Google Ukraine Pages From Ukraine
Google United Arab Emirates Whole Web
Google United Arab Emirates Pages From United Arab Emirates
Google United Kingdom Whole Web
Google United Kingdom Pages From United Kingdom
Google United States Whole Web
Google Venezuela Whole Web
Google Venezuela Pages From Venezuela
Google Vietnam Whole Web
Google Vietnam Pages From Vietnam
Yahoo Global
Yahoo Australia
Yahoo Austria
Yahoo Canada
Yahoo Denmark
Yahoo Finland
Yahoo France
Yahoo Germany
Yahoo Hong Kong
Yahoo India
Yahoo Ireland
Yahoo Italy
Yahoo Netherlands
Yahoo New Zealand
Yahoo Norway
Yahoo Poland
Yahoo Romania
Yahoo Spain
Yahoo Sweden
Yahoo Taiwan
Yahoo United Kingdom
Yahoo United States
Bing Global
Bing Australia
Bing Austria
Bing Canada
Bing Denmark
Bing Finland
Bing France
Bing Germany
Bing India
Bing Ireland
Bing Italy
Bing Netherlands
Bing New Zealand
Bing Norway
Bing Poland
Bing Romania
Bing Spain
Bing Sweden
Bing Taiwan
Bing United Kingdom
Bing United States