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

Response Data

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

Response data

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

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

Response data

Company data format:

company.addSite

This method adds a new site to a company.

Request parameters

Response data

company.getSites

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

Request parameters

Response data

Site data format:

Campaign data format:

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

Response data

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

Response data

company.getUsers

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

Request parameters

Response data

User data format:

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

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

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

Response data

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

Response data

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

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

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

Response data

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

Response data

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

Response data

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

Response data

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

Response data

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

Response data

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

Response data

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:

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