API Basics
The Authoritas API is divided into three sections:
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:
- The number of keywords that can be ranked per API call, where relevant.
- The number of pages that are Spidered for sites added through the API.
- The number of back-links that can be fetched for sites added through the API.
System Methods
These methods are used to access data about the Authoritas system.
system.getVersion
This method gets the current version of the API. This can be used to check that the API documentation is for the correct version of the API.
Request Parameters
Parameter Name | Type | Description |
---|---|---|
hash | string | Cryptographic hash data – see authentication parameters |
domain | string | Requesting domain – see authentication parameters |
timestamp | string | Request timestamp – see authentication parameters |
salt | string | Cryptographic salt – see authentication parameters |
Response Data
Parameter Name | Type | Description |
---|---|---|
api_version | string | The version number of the API |
Company Methods
These methods are used to create, query and modify data about companies on the Authoritas system. Users and sites all belong to companies.
company.addResellerClient
This method adds a new company to the Authoritas system as a child company of a reseller, and creates an admin user for the new company. If the company is added successfully, the Authoritas ID of the new company is returned. This ID should be stored and used for subsequent operations on that company.
Request parameters
Parameter Name | Type | Description |
---|---|---|
hash | string | Cryptographic hash data – see authentication parameters |
domain | string | Requesting domain – see authentication parameters |
timestamp | string | Request timestamp – see authentication parameters |
salt | string | Cryptographic salt – see authentication parameters |
company_name | string | Name for the new company |
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.
|
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:
|
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:
|
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.
|
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