API Basics

The Authoritas API is divided into three sections:

1. Company functions
2. Site functions
3. 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.

Authentication Parameters

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:

1. The number of keywords that can be ranked per API call, where relevant.
2. The number of pages that are Spidered for sites added through the API.
3. 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 targeting. 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"
},
...

Reference Data

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 (Countries)

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

• API Basics
  
• Accessing the API
  
• Request Format
• Response Format
• Authentication Parameters
  
• Usage Limits
  
• Company Methods
• System Methods
  
• Site Methods
• Reference Data
• Supported Markets (Countries)
• Supported Search Engines