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.

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 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
    pagerank = 9
    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 NameTypeDescription
hashstringCryptographic hash data – see authentication parameters
domainstringRequesting domain – see authentication parameters
timestampstringRequest timestamp – see authentication parameters
saltstringCryptographic salt – see authentication parameters
site_idintegerThe id of the desired site in our database
campaign_idintegerThe id of the desired campaign in our database
periodstringThe desired period (1day, 7days, 30days, lastmonth, 3months, 6months,  2016,  2015, wholecampaign)
domain_aliasbooleanActive or disabled domain alias functionality. (This is only available for enterprise packages)
offsetintegerThe offset of the keywords ranking in our database
limitintegerLimit the number of returned keywords (max. value is 350)

Response data

Parameter NameTypeDescription
organicarrayAn 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 NameTypeDescription
hashstringCryptographic hash data – see authentication parameters
domainstringRequesting domain – see authentication parameters
timestampstringRequest timestamp – see authentication parameters
saltstringCryptographic salt – see authentication parameters
site_idintegerThe id of the desired site in our database
campaign_idintegerThe id of the desired campaign in our database
datestringThe desired date (format yyyy-mm-dd)
domain_aliasbooleanActive or disabled domain alias functionality. (This is only available for enterprise packages)
offsetintegerThe offset of the keywords ranking in our database
limitintegerLimit the number of returned keywords (max. value is 350)
competitivebooleanShow competitor’s data

 

Response data

Parameter NameTypeDescription
organicarrayAn 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 NameTypeDescription
hashstringCryptographic hash data – see authentication parameters
domainstringRequesting domain – see authentication parameters
timestampstringRequest timestamp – see authentication parameters
saltstringCryptographic salt – see authentication parameters
site_idintegerThe id of the desired site in our database
campaign_idintegerThe id of the desired campaign in our database
offsetintegerThe offset of the keywords ranking in our database
limitintegerLimit the number of returned keywords (max. value is 2,000)

 

Response data

Parameter NameTypeDescription
organicarrayAn 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
      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",
     "results_order": "a:2:{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;}}",
     "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 NameTypeDescription
hashstringCryptographic hash data – see authentication parameters
domainstringRequesting domain – see authentication parameters
timestampstringRequest timestamp – see authentication parameters
saltstringCryptographic salt – see authentication parameters
site_idintegerThe id of the desired site in our database
campaign_idintegerThe id of the desired campaign in our database

Response data

Parameter NameTypeDescription
keywords_groupsarrayAn 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 NameTypeDescription
hashstringCryptographic hash data – see authentication parameters
domainstringRequesting domain – see authentication parameters
timestampstringRequest timestamp – see authentication parameters
saltstringCryptographic salt – see authentication parameters
site_idintegerThe id of the desired site in our database
campaign_idintegerThe id of the desired campaign in our database

Response data

Parameter NameTypeDescription
categoriesarrayAn 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 NameTypeDescription
hashstringCryptographic hash data – see authentication parameters
domainstringRequesting domain – see authentication parameters
timestampstringRequest timestamp – see authentication parameters
saltstringCryptographic salt – see authentication parameters
site_idintegerThe id of the desired site in our database
campaign_idintegerThe id of the desired campaign in our database
datestringThe desired date (format yyyy-mm-dd)
keyword_group_idintegerThe id of the desired keyword group (-1: All keywords groups, 0: Un-grouped)
category_idintegerThe id of the desired category (-1: All categories)

Response data

Parameter NameTypeDescription
market_visibilityarrayAn 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

Find out how our platform can help your agency or enterprise