Standard API Data

Standard API Data

Standard API Overview

seoClarity's API provides you programmatic access to a wealth of data, statistics and information collected by the seoClarity platform. The API is designed to be extremely simple to use and flexible to accommodate a wide range of integration needs. Clients may use the API to bring in the rich data set into their own internal data warehouses, or build specific applications that leverage our data to power their own workflows. The API is RESTful (no, we don’t mean its lazy, it’s a technical term) and results are delivered in a simple XML format via simple HTTP requests.

There is a query limit which is based on the subscription and the count of the keywords being tracked in the platform. Clients who have API access are granted (31:1) API call to tracked keyword search query ratio, where they can make 31 calls per month, for each tracked keyword search query. Additional API methods, like seoClarity.dev, and datasets are available by request. Please inquire with your Client Success Manager or support@seoclarity.net

Background & Requirements for the standard API

In order to get started with using the API, you will need the following: 1) An seoClarity account, 2) Familiarity with how to use an API, and 3) An API Access token. In order to obtain an API access token, send a request to your client success team member. They will then have a unique token generated for each domain. This means if API is needed for multiple domains, then multiple tokens will need to be generated. The API Access token is like a password and allows our web services to protect data and validate access to it. You should store and protect it just like you would store and protect your account password - with great care. Never share the access token with anyone else.

Standard API Limits

There are 2 types of limits on the API usage:
  1. A "query" limit that determines the number of times you can query the API.
    Quotas are set at the time of generating a token and depend on the number of elements (keywords/URLs) you track in your account. There are generous rate limits in place for clients to allow for retrieving all the data offered through the API's for each element they track in the seoClarity platform. Requests or quotas for requests are set at a domain + user level, i.e. each domain has a fixed quota of API calls and this quota can be distributed across all the authorized users of that account by an administrator. Again, let your client success team member know if you need the specific limits or the distribution changed by user.
  2. A "rate" limit that determines how fast the API can be queried. We urge everyone using the API to limit requests to the API no more than 1 per second. If you need to query faster, let us know so we can provide you a solution for your needs.

Note on row limits:
  1. By default, Managed Data APIs return 10 rows per request.
  2. You can increase this limit up to a maximum of 100 rows by using the limit parameter.
Pagination:
  • To retrieve more than 100 rows, use the offset parameter to set the starting row.
  • Send multiple requests, adjusting the offset each time until the full dataset is retrieved.

API Pricing

The pricing philosophy behind the API is simple – Data for any element that you already track in your seoClarity account is available to you free of charge through the API. For example, if you’d like to retrieve the ranking data for any keyword you track in seoClarity, there is no charge for the data. If you’d like access to the full data set of what is available in our platform (for example, search volume data for keywords you don’t track in your seoClarity account) for research projects or for a one-time analysis, there is a charge for each request. In the list of the methods provided below, we will list out the methods that would incur a separate charge and the ones you have available as part of your subscription.

Standard API Data

The following data sets can be accessed via the API:

Managed Dataset:
  1. Managed Keywords - Returns the managed keywords you track in the platform.
  2. Managed Pages - Returns the managed pages you track in the platform.
  3. Tags - Retrieve a list of the keyword / page tags in the account and the unique ID assigned to each tag
  4. Keyword Rankings - ranking data for keywords you track in the platform.
  5. Tag Summary - list of summarized analytics, rank, and other metrics for a tag.
  6. Tag Detail - Query tag detail information.
  7. Add / Remove Keywords - Add or Remove managed keywords from Rank Intelligence.
  8. Add Tags - Add Keyword or Page Tags to Rank Intelligence / Page Clarity.
  9. Update Tags - Update Keyword or Page Tags in Rank Intelligence / Page Clarity.
  10. Delete Tags - Delete Keyword or Page Tags in Rank Intelligence / Page Clarity.
Other Datasets:
  1. Backlinks (Paid Call) - Retrieves backlink information for any url from seoClarity’s database.
  2. Backlinks Summary (Paid Call) - Retrieves backlink summary information for any url from seoClarity’s database.
  3. Content Ideas - Search for content ideas based on what users are searching for (now located at  seoclarity.dev)
  4. Content Distribution - Query and return the Content Distribution Tracker table data and detail information.
  5. Content Similarity Check - Compare the percentage similarity of content between any two pages.
Domain Settings:
  1. User Administration - Manage users easily and efficiently.
  2. API Usage - API Token Usage

API Calls /help

Description: Show a list for all API call commands.
Cost: Free
Parameters: N/A

Sample Response
<commands>
<command>
<name>keyword</name>
<version>v2.0</version>
<description>Query keyword Rank (private, for more details, please access /help/keyword)</description>
</command>
<command>
<name>markets</name>
<version>v1.0</version>
<description>List all markets</description>
</command>
<command>
<name>help</name>
<version>v1.0</version>
<description>List all commands</description>
</command>
<command>
<name>event</name>
<version>v1.0</version>
<description>Query Events (private, for more details, please access /help/event)</description>
</command>
<command>
<name>tag</name>
<version>v1.0</version>
<description>Query tag (private, for more details, please access /help/tag)</description>
</command>
<command>
<name>tagdetail</name>
<version>v1.0</version>
<description>Query tag detail information (private, for more details, please access /help/tagdetail)</description>
</command>
<command>
<name>tagsummary</name>
<version>v1.0</version>
<description>Query tag summary information (private, for more details, please access /help/tagsummary)</description>
</command>
<command>
<name>usage</name>
<version>v1.0</version>
<description>API Token Usage Report (private, for more details, please access /help/usage)</description>
</command>
</commands>

/help/{Command}

Cost: Free
Request format: https://api.seoclarity.net/seoClarity/help/{command}              
Parameters:
  1. Command: The name of command you intend to check

Sample Response
<parameters>
<parameter>
<name>urlType</name>
<desc>
URL Type(1: Target Url, 3: Competitor Url) ,can't be null
</desc>
<example>urlType=1</example>
</parameter>
<parameter>
<name>eventType</name>
<desc>Event Type(1: content change), can't be null</desc>
<example>eventType=1</example>
</parameter>
</parameters>

Managed Elements

Managed Pages

Description: Return all the managed URLs (private, for more details, please access /help/geturl)
Cost: Free
Request Format:
Parameters:
  1. Access_token
    1. The access_token is a long string of letters and numbers that you include in API calls to let us know what user you are making the API call and what permissions your app has for that user
  1. Limit
    1. Specifies the maximum number of rows to return
    2. Default limit is 10
    3. Maximum limit is 100
    4. Parameter can be null
  2. Offset
    1. Specifies the offset of the first row to return
    2. The offset of the initial row is 0
    3. Parameter can be null
Sample Response
<Urls>
<url>
</url>
<url>
<targetUrl>
</targetUrl>
</url>
</Urls>

Tags

Description: The Tag API call is a high level call that allows users to retrieve a list of the keyword and/or page tags in the account and the unique ID assigned to each tag.

It allows access to:
  • List of tags in your seoClarity account (Keyword and/or Page tags)
  • A unique tag ID for each tag
The unique tag ID retrieved using this call can then be used in conjunction with other Tag calls to get more granular data on specific tags.
Only keyword and page tags tracked in your seoClarity account are available through this API call.
Cost: Free
Request Format:

Parameters:
  1. Access_token
    1. The access_token is a long string of letters and numbers that you include in API calls to let us know what user you are making the API call and what permissions your app has for that user
  2. Type
    1. Tag Type
    2. Default show all tags
    3. Example: 0: All, 1: UrlTag,  2: KeywordTag
  3. Limit
    1. Specify the maximum number of rows of return
    2. Default value is 10
    3. Maximum value is 100
    4. Parameter could be null
  4. Offset
    1. Specify the offset of the first row of return
    2. The default value is 0
    3. Parameter could be null
  5. WT
    1. The format of data retrieved you expect, including XML and JSON and CSV, from this API call
    2. Example: wt=xml ( json or scv)
Sample Response
XML:
<tags>
<tag>
<tagId>2</tagId>
<tagName>Florida</tagName>
<tagType>Url Tag</tagType>
</tag>
<tag>
<tagId>2622</tagId>
<tagName>Alabama</tagName>
<tagType>Url Tag</tagType>
</tag>
<tag> 
…
…
…
</tags>

 
JSON:
[{"tagId":"2","tagName":"Florida","tagType":"Url Tag"},{"tagId":"2622","tagName":"Alabama","tagType":"Url Tag"},{"tagId":"3210","tagName":"Top Ranked Keywords","tagType":"Keyword Tag"},{"tagId":"23929","tagName":"Homepage","tagType":"Url Tag"},{"tagId":"25329","tagName":"Tree of PageTag 1","tagType":"Url Tag"},{"tagId":"35745","tagName":"Campaigns","tagType":"Url Tag"},{"tagId":"36708","tagName":"Beach Rentals","tagType":"Keyword Tag"},{"tagId":"36709","tagName":"Pet Friendly Condos","tagType":"Keyword Tag"},{"tagId":"36710","tagName":"Pet Friendly Rentals","tagType":"Keyword Tag"},{"tagId":"37860","tagName":"Texas NEW","tagType":"Keyword Tag"}]
 
CSV:
tagId,tagName,tagType
2,Florida,"Url Tag"
2622,Alabama,"Url Tag"
3210,"Top Ranked Keywords","Keyword Tag"
23929,Homepage,"Url Tag"
25329,"Tree of PageTag 1","Url Tag"
35745,Campaigns,"Url Tag"
36708,"Beach Rentals","Keyword Tag"
36709,"Pet Friendly Condos","Keyword Tag"tag
36710,"Pet Friendly Rentals","Keyword Tag"
37860,"Texas NEW","Keyword Tag"

Keyword Rankings

Description: The keyword API call is a comprehensive call to retrieve ranking data related to any keyword in your account. It allows access to ranking information for
  • Returns data at the individual keyword level
  • For a specific date or date range up to 30 days
The API call returns the ranking and each of the ranked URLs for your own domain as also each Universal Competitor for your domain. Only keywords tracked in your seoClarity account are available through this API call.

Cost: "keyword" (Free)

Request Format:

Parameters:
  • access_token: string
    • required: yes
    • description: seoClarity user authorization api key
    • Style: Comma separated values
  • sdate: string <date>
    • required: yes
    • starting date
    • format: yyyymmdd
    • minDate: 20160101
  • edate: string <date>
    • required: yes
    • tarting date
    • format: yyyymmdd
    • maxDate: current date
  • engine: string
    • required: Yes
    • Default: google
    • Style: Comma separated values
    • supported values: google, yahoo, bing, baidu, yandex, naver, google-mobile, 360 search
  • market: string
    • required: yes
    • Default: en-us
    • Style: Comma separated values
    • example of supported values: en-us , en-au, en-uk , en-ca , fr-ca, fr-fr ,zh-cn
  1. kname: string
    1. required: no
    2. description: keyword name
    3. Style: Comma separated values
    4. Format: encoded
  2. Tagid
    1. requried: no
    2. description: enter tag ID (can be retrieved by downloading all in Rank intelligence > keyword tag tab)
  1. Limit
    1. required: no
    2. description: specifies the maximum number of rows returned 
    3. deafult value: 10
    4. Min: 1 ; Max: 100
  2. Offset
    1. required: no
    2. description: specify the offset of the first row returned
    3. deafult value: 0
  3. plpType: string
    1. required: no
    2. Description: Includes all preferred landing page associations
    3. Default value: false
    4. supported values: true, false
    5. Style: Comma separated values
  4. Competitor
    1. required: no
    2. description: enter competitor domain
  5. device
    1. required: no
    2. description: enter search engine to query
    3. default value: d
    4. supported values:
      1. d - desktop
      2. m - mobile
  6. Type
    1. required: no
    2. description: response data format
    3. default value: xml
    4. supported values:
      1. xml
      2. csv
  7. enableLocation
    1. required: no
    2. description: whether to use location
    3. default value: false
    4. supported values:
      1. true
      2. false
  8. Oid
    1. required: no
    2. description: specify the domainID 
Request Example

Response Example
{
  "keyword name": "string",
  "date": "string",
  "highestTrueRank": "string",
  "highestWebRank": "string",
  "highestRankURL": "string",
  "highestLocalRank": "string",
  "highestNewsRank": "string",
  "highestImageRank": "string",
  "highestVideoRank": "string",
  "avgSearchVolume": "string",
  "competitorName": "string",
  "landingPage": "string",
  "rank": "string",
  "preferredLandingPage": "string",
  "PLPTrueRank": "string",
  "PLPWebRank": "string"
}

Keyword / Page Tags
Description: The Tag API call is a high level call that allows users to retrieve a list of the keyword and/or page tags in the account and the unique ID assigned to each tag.

It allows access to:
  1. List of tags in your seoClarity account (Keyword and/or Page tags)
  2. A unique tag ID for each tag
The unique tag ID retrieved using this call can then be used in conjunction with other Tag calls to get more granular data on specific tags.
Only keyword and page tags tracked in your seoClarity account are available through this API call.
Cost: Free
Request Format:

Parameters:
  1. Access_token
    1. The access_token is a long string of letters and numbers that you include in API calls to let us know what user you are making the API call and what permissions your app has for that user
  2. Type
    1. Tag Type
    2. Default show all tags
      1. Example: 0: All, 1: UrlTag,  2: KeywordTag
  3. Limit
    1. Specify the maximum number of rows of return
    2. Default value is 10
    3. Maximum value is 100
    4. Parameter could be null
  4. Offset
    1. Specify the offset of the first row of return
    2. The default value is 0
    3. Parameter could be null
  5. WT
    1. The format of data retrieved you expect, including XML and JSON and CSV, from this API call
      1. Example: wt=xml ( json or scv)
Sample Response
XML:

<tags>
<tag>
<tagId>2</tagId>
<tagName>Florida</tagName>
<tagType>Url Tag</tagType>
</tag>
<tag>
<tagId>2622</tagId>
<tagName>Alabama</tagName>
<tagType>Url Tag</tagType>
</tag>
<tag> 
</tags>

 
JSON:

[{"tagId":"2","tagName":"Florida","tagType":"Url Tag"},{"tagId":"2622","tagName":"Alabama","tagType":"Url Tag"},{"tagId":"3210","tagName":"Top Ranked Keywords","tagType":"Keyword Tag"},{"tagId":"23929","tagName":"Homepage","tagType":"Url Tag"},{"tagId":"25329","tagName":"Tree of PageTag 1","tagType":"Url Tag"},{"tagId":"35745","tagName":"Campaigns","tagType":"Url Tag"},{"tagId":"36708","tagName":"Beach Rentals","tagType":"Keyword Tag"},{"tagId":"36709","tagName":"Pet Friendly Condos","tagType":"Keyword Tag"},{"tagId":"36710","tagName":"Pet Friendly Rentals","tagType":"Keyword Tag"},{"tagId":"37860","tagName":"Texas NEW","tagType":"Keyword Tag"}]

CSV:

tagId,tagName,tagType
2,Florida,"Url Tag"
2622,Alabama,"Url Tag"
3210,"Top Ranked Keywords","Keyword Tag"
23929,Homepage,"Url Tag"
25329,"Tree of PageTag 1","Url Tag"
35745,Campaigns,"Url Tag"
36708,"Beach Rentals","Keyword Tag"
36709,"Pet Friendly Condos","Keyword Tag"tag
36710,"Pet Friendly Rentals","Keyword Tag"
37860,"Texas NEW","Keyword Tag"

Tag Summary

"tagsummary" (Free)
Description: The Tag API call is a high level call that allows users to retrieve a list of the keyword and/or page tags in the account and the unique ID assigned to each tag. 

It allows access to:
  1. List of keyword or page tags in your seoClarity account 
  2. Returns data at the tag level based on the tagID
Cost: Free

Request Format:

Parameters:
  • access_token: string
    • required: yes
    • description: seoClarity user authorization api key
    • Style: Comma separated values
  1. Tagid
    1. required: Yes
    2. description: enter tag ID (can be retrieved by downloading all in Rank intelligence > keyword tag tab)
  2. sdate: string <date>
    1. required: yes
    2. starting date
    3. format: yyyymmdd
    4. minDate: 20160101
  3. edate: string <date>
    1. required: yes
    2. end date
    3. format: yyyymmdd
  4. Limit
    1. required: no
    2. description: specifies the maximum number of rows returned 
    3. deafult value: 10
    4. Min: 1 ; Max: 100
  5. Offset
    1. required: no
    2. description: specify the offset of the first row returned
    3. deafult value: 0
  6. Wt
    1. required: no
    2. description: response data format
    3. default value: xml
    4. supported values
      1. xml
      2. json
      3. csv
  7. specOid
    1. required: no
    2. description: specify the domainID
  8. engineName
    1. required: no
    2. description: specify search engine
    3. default value: google
    4. supported values: google, yahoo, bing, baidu, naver, yandex, 360 search, google-mobile
  9. market: string
    1. required: no
    2. Default value: no
    3. example of supported values: en-us , en-au , en-uk, en-ca , fr-ca, fr-fr ,zh-cn
      1. full list of available markets can be retrieved at: https://api.seoclarity.net/markets
  10. device
    1. required: no
    2. description: enter search engine to query
    3. default value: d
    4. supported values:
      1. d - desktop
      2. m - mobile
    5. Style: Comma separated values
  11. isIgnoreDeletedKeywords: boolean
    1. required:  no
    2. description:'True' will ignore deleted keywords whereas 'False' will include deleted keywords
    3. default value: true
    4. supported values: true, false
    5. Style: Comma separated values
  12. isNationalLevel: boolean
    1. required: no
    2. Description: 'True' will view rankings at a national level whereas 'False' will not view rankings at a national level
    3. Default value: True
    4. Style: Comma separated values
  13. isTrueRank: boolean
    1. required: no
    2. description:' True' will view rankings in True Rank whereas 'False' will view rankings in Web Rank
    3. Default value: True
    4. Style: Comma separated values
  14. City
    1. required: no
    2. description: city name
    3. default value: no
  15. cityID
    1. required: no
    2. description: city Id
    3. default value: 0
  16. competitorDomain
    1. required: no
    2. description: competitor domain
    3. default value: no
  17. engineId
    1. required: no
    2. description: search engine Id
    3. default value: 0
  18. languageId
    1. required: no
    2. description: language Id
    3. default value: 0
Response Example
{
  "tags": {
    "tagName": "string",
    "geo_location": "string",
    "tagType": "string",
    "logDate": "yyyymmdd",
    "totalKeywords": 0,
    "totalKeywordsWithout101": 0,
    "rankInPage1": 0,
    "rankInPage2": 0,
    "rankInPage3": 0,
    "rankInPage4": 0,
    "rankInPage5": 0,
    "KeywordCountAtRank1": 0,
    "KeywordCountAtRank2": 0,
    "KeywordCountAtRank3": 0,
    "KeywordCountAtRank4": 0,
    "KeywordCountAtRank5": 0,
    "KeywordCountAtRank6": 0,
    "KeywordCountAtRank7": 0,
    "KeywordCountAtRank8": 0,
    "KeywordCountAtRank9": 0,
    "KeywordCountAtRank10": 0,
    "keywordCountRankInTop3": 0,
    "keywordCountRankInTop10": 0,
    "keywordCountRankInTop30": 0,
    "keywordCountRankInTop50": 0,
    "keywordCountRankInTop100": 0,
    "searchVolumeTop1": 0,
    "searchVolumeTop2": 0,
    "searchVolumeTop3": 0,
    "searchVolumeTop4": 0,
    "searchVolumeTop5": 0,
    "searchVolumeTop6": 0,
    "searchVolumeTop7": 0,
    "searchVolumeTop8": 0,
    "searchVolumeTop9": 0,
    "searchVolumeTop10": 0,
    "searchVolumeTop100": 0,
    "estdTraffic": 0,
    "avgSearchVolume": 0,
    "avgSearchVolumeWithout101": 0,
    "avgRank": 0,
    "avgRankWithout101": 0,
    "wtdAvgRank": 0,
    "wtdAvgRankWithout101": 0,
    "shareOfVoice": 0,
    "shareOfVoiceWithout101": 0,
    "shareOfMarket": 0,
    "shareOfMarketWithout101": 0
  }
}


Tag Detail

Description: Query tag detail information (private, for more details, please access /help/tagdetail)
Cost: Free
Parameters:
  1. Access_token
    1. The access_token is a long string of letters and numbers that you include in API calls to let us know what user you are making the API call and what permissions your app has for that user
  2. TagID
    1. Tag ID
    2. Parameter can be null
  3. WT
    1. The format of data retrieved you expect, including XML and JSON and CSV, from this API call.
    2. Example: wt=xml ( json or scv)

Sample Response
XML :

<tags>
<tag>
<tagId>77511</tagId>
<tagName>ARIZON KEYWORDS-TEST</tagName>
<tagType>Keyword Tag</tagType>
<elementId>504217</elementId>
<elementName>pet friendly vacation rentals</elementName>
</tag>
<tag>
<tagId>77511</tagId>
<tagName>ARIZON KEYWORDS-TEST</tagName>
<tagType>Keyword Tag</tagType>
<elementId>513870</elementId>
<elementName>pet friendly vacation rentals in florida</elementName>
</tag>
</tags>

JSON:

[{"tagId":"77511","tagName":"ARIZON KEYWORDS-TEST","tagType":"Keyword Tag","elementId":"504217","elementName":"pet friendly vacation rentals"},{"tagId":"77511","tagName":"ARIZON KEYWORDS-TEST","tagType":"Keyword Tag","elementId":"513870","elementName":"pet friendly vacation rentals in florida"},{"tagId":"77511","tagName":"ARIZON KEYWORDS-TEST","tagType":"Keyword Tag","elementId":"514033","elementName":"venice florida"},{"tagId":"77511","tagName":"ARIZON KEYWORDS-TEST","tagType":"Keyword Tag","elementId":"514625","elementName":"pet friendly destin"},{"tagId":"77511","tagName":"ARIZON KEYWORDS-TEST","tagType":"Keyword Tag","elementId":"543563","elementName":"ft. myers dog friendly"},{"tagId":"77511","tagName":"ARIZON KEYWORDS-TEST","tagType":"Keyword Tag","elementId":"554769","elementName":"ft. myers pet friendly vacation homes"},{"tagId":"77511","tagName":"ARIZON KEYWORDS-TEST","tagType":"Keyword Tag","elementId":"556549","elementName":"pet friendly rentals in destin fl"},{"tagId":"77511","tagName":"ARIZON KEYWORDS-TEST","tagType":"Keyword Tag","elementId":"618734","elementName":"oceanfront pet friendly lodging in florida"},{"tagId":"77511","tagName":"ARIZON KEYWORDS-TEST","tagType":"Keyword Tag","elementId":"1079844","elementName":"dog rental"},{"tagId":"77511","tagName":"ARIZON KEYWORDS-TEST","tagType":"Keyword Tag","elementId":"1120729061","elementName":"kuch kuch hota hai gazebo"}]

CSV:

tagId,tagName,tagType,elementId,elementName
77511,"ARIZON KEYWORDS-TEST","Keyword Tag",504217,"pet friendly vacation rentals"
77511,"ARIZON KEYWORDS-TEST","Keyword Tag",513870,"pet friendly vacation rentals in florida"
77511,"ARIZON KEYWORDS-TEST","Keyword Tag",514033,"venice florida"
77511,"ARIZON KEYWORDS-TEST","Keyword Tag",514625,"pet friendly destin"
77511,"ARIZON KEYWORDS-TEST","Keyword Tag",543563,"ft. myers dog friendly"
77511,"ARIZON KEYWORDS-TEST","Keyword Tag",554769,"ft. myers pet friendly vacation homes"
77511,"ARIZON KEYWORDS-TEST","Keyword Tag",556549,"pet friendly rentals in destin fl"
77511,"ARIZON KEYWORDS-TEST","Keyword Tag",618734,"oceanfront pet friendly lodging in florida"
77511,"ARIZON KEYWORDS-TEST","Keyword Tag",1079844,"dog rental"
77511,"ARIZON KEYWORDS-TEST","Keyword Tag",1120729061,"kuch kuch hota hai gazebo"


Add / Remove Keywords

“addremovekeywords” Cost:Free/Paid
Request Format 
Parameters:
  1. Access_token
    1. The access_token is a long string of letters and numbers that you include in API calls to let us know what user you are making the API call and what permissions your app has for that user
  2. Keywordlist
    1. Keyword Names, which need encode, is composed of several keyword using ‘!_!’ string as joint
    2. Maximum size is 50 keywords
    3. Example: pet+home!_!pet!_!shoes
    4. Parameter cannot be null
  3. Type
    1. Operation Type
    2. Support function of addition and remove
    3. Example: type=add or type=remove
    4. Parameter cannot be null
Sample Response

Add :

<messages>
<message>Your request is in queue, please stand by.</message>
</messages>

Remove:

<messages>
<message>Your request is in queue, please stand by.</message>
</messages>

Add Tags

The ‘addtags’ API call is a call that allows for the creation of tags.
Cost: Free
Request Format:

Parameters:
  1. Access_token
    1. The access_token is a long string of letters and numbers that you include in API calls to let us know what user you are making the API call and what permissions your app has for that user.
  2. Tags
    1. Tag name, which needs encode
    2. If you want to add more tags please use string of ‘!_!’ as delimiter
    3. Maximum size is 100
    4. Example: pet+home or pet+home!_!pet!_!shoes
    5. Parameter cannot be null
  3. Type
    1. Type=1 creates a page tag
    2. Type=2 creates a keyword tag
Sample Response
<messages>
<message>Your request is in queue, please stand by.</message>
</messages>

Update Tags

Description: The update tag API call is a call that allows for a specific tag to be changed.
Cost: Free
Request Format:
Parameters:
  1. Access_token
    1. The access_token is a long string of letters and numbers that you include in API calls to let us know what user you are making the API call and what permissions your app has for that user.
  2. TagIDName
    1. Tag ID and Tag Name, which needs encode
    2. You couldupdate 1 tag name per query
    3. Example: 123!_!pet+home
    4. Parameter cannot be null
Sample Response
<messages>
<message>Your request is in queue, please stand by.</message>
</messages>

Delete Tags

Description: The delete tags API call is a call that allows for the deletion of tags.
Cost: Free
Request Format
Parameters:
  1. Access_token
    1. The access_token is a long string of letters and numbers that you include in API calls to let us know what user you are making the API call and what permissions your app has for that user.
  2. Tags
    1. Tag name, which needs encode
    2. If you want to add more tags please use string of ‘!_!’ as delimiter
    3. Maximum size is 100
    4. Example: pet+home or pet+home!_!pet!_!shoes
    5. Parameter cannot be null
  3. Type
    1. Type=1 creates a page tag
    2. Type=2 creates a keyword tag
Sample Response
<messages>
<message>Your request is in queue, please stand by.</message>
</messages>

Other Datasets

Description: The backlinks API call is an ad-hoc call that allows for retrieval of backlink information for any url from seoClarity’s master database.
There is an additional charge for each call. This is data from the Link Profile Table within the backlinks tab. Please contact sales@seoclarity.net for specifics.

Content Distribution

Description: Query and return the Content Distribution Tracker table data and detail information.
Cost: Free
Request Format:

Parameters:
  1. Access_token
    1. The access_token is a long string of letters and numbers that you include in API calls to let us know what user you are making the API call and what permissions your app has for that user.
    2. cID (optional)
    3. Input content id number
    4. This 3 digit number is available with an initial call where cID is null
    5. (see sample response)
  2. WT (optional)
    1. WT is the format in which the response should be returned
    2. Parameter can be null.
    3. Example: endpoint=json

Sample Response
<contentDistribution>
<contentId>611</contentId>
<contentText>
Find pet friendly vacation rentals, homes, lodging, accommodation, condos, and hotels that permit and welcome pets.
</contentText>
<acquisitionType>Other</acquisitionType>
<acquisitionOther>From site</acquisitionOther>
<createDate>01/13/2014</createDate>
<countOfResult>-</countOfResult>
<countOfLink>0</countOfLink>
</contentDistribution>

Content Similarity Check

Description: The SimCheck API is built to allow Enterprises to compare the percentage similarity of content between any two pages. The service is built to closely mimic how search engines evaluate similarity. 

The SimCheck API is a complex analysis service that consists of multiple steps. For each request submitted, here are the steps executed by the API.
  1. Page Crawl to retrieve the raw HTML of the page
  2. Content Extraction to parse the key content using a machine learning algorithm that excludes navigational and common header and footer elements
  3. Similarity Checking that applies NLP techniques to analyzes the crawled content and determine similarity percentage.

Cost: Free
Request Format:

Parameters:
While there are a number of parameters for configuring SimCheck, most clients will not need to change anything to get excellent results out of the box.
  1. Main_url
    1. Parameter type os query
    2. Data Type is string
  2. Sub_urls
    1. Parameter Type is query
    2. Data Type is string
    3. URLs are separated by commas (,)
  3. Access_token
    1. Parameter Type is query
    2. Data Type is string
    3. seoClarity provided API token
  4. distance_metric (Optional)
    1. Parameter Type is query
    2. Data Type is string
    3. Default is cosine
    4. Currently supports jaccard, cosine, fuzzy, simhash
  5. max_ngram (Optional)
    1. Parameter Type is query
    2. Data Type is string
    3. Default is 1
    4. Maximum is 20
  6. min_ngram (Optional)
    1. Parameter Type is query
    2. Data Type is string
    3. Default is 1
    4. Minimum is 1
  7. unit (Optional)
    1. Parameter Type is query
    2. Data Type is string
    3. default is word  

Sample Response
Given the multi-step nature of the process, there are multiple errors that the SimCheck could encounter. Here is a list of the error messages and what they mean
{
  "similarity": "[[url1, matching_percentage1], [url2, matching_percentage2], [url3, matching_percentage3], [url4, \"Page not found]\"], [url4, \"Page not found]\"],...]",
  "error": "False (boolean) if request successfully, else return error message (string)"
}

"error": false,

 This indicates all the steps were completed successfully.

Sample Reponse
{
"error": false,
65.88]]
}

"error": "Main page is empty",

This error is returned when the content extractor does not manage to identify any substantial content to analyze on the page. A page that contains only links, or has very short sentences scattered throughout the page would cause this issue.

Rank Intelligence Keyword Bulk Rankings

Rank Intelligence Keyword Bulk Rankings provides richer structured data. This API only supports JSON format and allows access to ranking extracts from the last 12 months. Clients can use it to download top X ranking URLs (default: top 30) and apply filters to retrieve own domain rankings, competitor rankings, or any domains' rankings.
  1. Integrates with the Storage Settings page, allowing clients to automatically store the data in their preferred location, such as Amazon S3, FTP, or GCS.
  2. Cost: Included with most subscriptions
  1. https://api.seoclarity.net/seoClarity/task/v1/dailyRanking/ranking
Request Format:
{
    "device": "desktop",
    "top": 10,
    "startDate": 20250101,
    "endDate": 20250103,
    "query": {
        "filters": [
            {
                "name": "domains",
                "operation": "ct",
                "value": "www.exampledomain.com"
            },
            {
                "name": "rank",
                "operation": "between",
                "value": "[1-10]"
            },
            {
                "name": "keyword",
                "operation": "ct",
                "value": "jumpsuit"
            }
        ]
    }
}

Sample Response:
{
    "info": {
        "status": "success",
        "date": "2025-01-03"
    },
    "searchParameters": {
        "id": 3357639,
        "searchEngine": "google.com",
        "country": "US",
        "language": "en",
        "device": "desktop",
        "keyword": "blue jumpsuit",
        "location": "national"
    },
    "searchInfo": {
        "cpc": 0.75,
        "searchVolume": 9900,
        "trueDemand": 0,
        "serpFilterButtonText": [
            "women's blue jumpsuit",
            "men's blue jumpsuit",
            "navy blue jumpsuit",
            "girls' blue jumpsuit",
            "denim blue jumpsuit",
            "blue jumpsuit nearby",
            "petite blue jumpsuit",
            "long blue jumpsuit",
            "floral blue jumpsuit",
            "shorts blue jumpsuit",
            "blue jumpsuit",
            "navy blue jumpsuit",
            "fashion nova blue jumpsuit",
            "plus blue jumpsuit",
            "blue jumpsuit sale",
            "target blue jumpsuit",
            "amazon blue jumpsuit",
            "regular blue jumpsuit",
            "jumpsuits & rompers blue jumpsuit",
            "nordstrom blue jumpsuit",
            "outfit blue jumpsuit",
            "pants blue jumpsuit",
            "dillard's blue jumpsuit",
            "black blue jumpsuit",
            "dress blue jumpsuit"
        ],
        "keywordDateAdded": "20220609",
        "preferredPages": [
            "https://www2.hm.com/en_us/productpage.0711416002.html"
        ]
    },
    "serpFeaturesFlag": {
        "app": "n",
        "img": "y",
        "news": "n",
        "video": "n",
        "localListing": "n",
        "ppcAds": "n",
        "answerBox": "n",
        "hotel": "n",
        "flights": "n",
        "pla": "n",
        "knowledgeGraph": "n",
        "fromsourcesacrosstheweb": "n",
        "findresultson": "n",
        "populardestinations": "n",
        "aio": "n",
        "popularRecipes": "n",
        "popularStore": "n",
        "discussionsandforums": "n",
        "buyingguide": "n"
    }
}

All Available Parameters at /dailyRanking/ranking
{
  "device": "mobile",
  "top": 20,
  "startDate": 20250101,
  "endDate": 20250101,
  "searchEngine": "google.com",
  "language": "en",
  "storageId": 0,
  "locationId": 0,
  "query": {
    "filters": [
      {
        "name": "domains",
        "operation": "ct",
        "value": "abc.com|def.com|xyz.com"
      },
      {
        "name": "rank",
        "operation": "<",
        "value": "50"
      },
      {
        "name": "search_volume",
        "operation": "between",
        "value": "[1-1000]"
      },
      {
        "name": "keyword",
        "operation": "ct",
        "value": "s"
      }
    ]
  }
}

dailyRanking/serpfeatures
Creates a task id to identify SERP feature rankings where your domain or competitors are ranking within any SERP features.
  1. https://api.seoclarity.net/seoClarity/task/v1/dailyRanking/serpfeature
​Request Format:
{
    "device": "desktop",
    "top": 5,
    "startDate": 20250101,
    "endDate": 20250103,
    "query": {
        "filters": [
            {
                "name": "domains",
                "operation": "ct",
                "value": "www.exampledomain.com"
            },
            {
                "name": "rank",
                "operation": "between",
                "value": "[1-5]"
            },
            {
                "name": "keyword",
                "operation": "ct",
                "value": "jumpsuit"
            }
        ]
    }
}

Sample Response:
{
    "info": {
        "status": "success",
        "date": "2025-01-01"
    },
    "searchParameters": {
        "id": 2971060,
        "searchEngine": "google.com",
        "country": "US",
        "language": "en",
        "device": "desktop",
        "keyword": "jumpsuits for women on sale",
        "location": "national"
    },
    "searchInfo": {
        "cpc": 0.6,
        "searchVolume": 480,
        "trueDemand": 0,
        "serpFilterButtonText": [
            "petite jumpsuits for women on sale",
            "black jumpsuits for women on sale",
            "jumpsuits for women on sale nearby",
            "plus jumpsuits for women on sale",
            "jumpsuits for women on sale under $25",
            "pink jumpsuits for women on sale",
            "cotton jumpsuits for women on sale",
            "long jumpsuits for women on sale",
            "floral jumpsuits for women on sale",
            "amazon jumpsuits for women on sale",
            "jumpsuits for women on sale",
            "spandex jumpsuits for women on sale",
            "green jumpsuits for women on sale",
            "white jumpsuits for women on sale",
            "dillard's jumpsuits for women on sale",
            "polyester jumpsuits for women on sale",
            "denim jumpsuits for women on sale",
            "gray jumpsuits for women on sale",
            "regular jumpsuits for women on sale",
            "nordstrom jumpsuits for women on sale",
            "tall jumpsuits for women on sale",
            "fashion nova jumpsuits for women on sale",
            "jcpenney jumpsuits for women on sale",
            "macy's jumpsuits for women on sale",
            "online jumpsuits for women on sale"
        ],
        "keywordDateAdded": "20220609",
        "preferredPages": [
            "https://www2.hm.com/en_us/sale/women/jumpsuits.html"
        ]
    },
    "serpFeaturesFlag": {
        "app": "n",
        "img": "y",
        "news": "n",
        "video": "n",
        "localListing": "n",
        "ppcAds": "n",
        "answerBox": "n",
        "hotel": "n",
        "flights": "n",
        "pla": "n",
        "knowledgeGraph": "n",
        "fromsourcesacrosstheweb": "n",
        "findresultson": "n",
        "populardestinations": "n",
        "aio": "n",
        "popularRecipes": "n",
        "popularStore": "n",
        "discussionsandforums": "n",
        "buyingguide": "n"
    }
}

All Available Parameters at /dailyRanking/serpfeature
{
  "device": "mobile",
  "top": 10,
  "startDate": 20250106,
  "endDate": 20250107,
  "searchEngine": "google.com",
  "language": "en",
  "storageId": 126563,
  "locationId": 0,
  "query": {
    "filters": [
      {
        "name": "domains",
        "operation": "ct",
        "value": "abc.com|def.com|xyz.com"
      },
      {
        "name": "brands",
        "operation": "ct",
        "value": "amazon|zara"
      },
      {
        "name": "brands",
        "operation": "eq",
        "value": "hm"
      },
      {
        "name": "rank",
        "operation": "<",
        "value": "50"
      },
      {
        "name": "search_volume",
        "operation": "between",
        "value": "[1-1000]"
      },
      {
        "name": "keyword",
        "operation": "ct",
        "value": ""
      }
    ]
  }
}

Domain Settings

The purpose of the user administration APIs is to enable client to manage users easily and efficiently. SCIM (System for Cross-domain Identity Management) is a standard protocol for automating user management across different applications. 

Upon request, seoClarity provides endpoints that allows clients the ability to add, update, delete or retrieve user info in real-time via an API. This streamlines account management and saves time and effor needed to perform these tasks directly in the seoClarity platform.

If interested in using this feature please contact support@seoclarity.net to get more information about how to get started. Below is a full list and documentation for the various 

Create a User

method: POST 
Authorization header: access_token 
Request Sample 
{ 
  "schemas": [ 
"urn:ietf:params:scim:schemas:core:2.0:User", 
"**urn:ietf:params:scim:schemas:extension:seoclarity:2.0:User**" 
  ], 
  "userName": "abc@company.com", 
  "company": "companyName", 
  "name": { 
"familyName": "Scim", 
"givenName": "User" 
  }, 
  "active": true, 
  "urn:ietf:params:scim:schemas:extension:seoclarity:2.0:User": { 
"permission": "sysadmin", 
"domainIdList": [4,256] 
  } 
} 

Fields:

Attribute 
Required? 
Description 
Example 
userName 
Y 
user email address 
name.familyName 
Y 
family name 
 
name.givenName 
Y 
given name 
 
active 
Y 
user’s status 
 
schemas 
Y 
Schema URI for representing users; include the value as indicated in the example 
"schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User", "urn:ietf:params:scim:schemas:extension:seoclarity:2.0:User"] | 
 
Permission 
N (defaults to “standard”) 
Values can be “sysadmin”, “standard” or “readonly standard” 
 


domainIdList 
N 
Defaults to the domainId of the domain associated with access_token used for the API call. 
 

Response Sample:
{ 
  "schemas": [ 
"urn:ietf:params:scim:schemas:core:2.0:User", 
"urn:ietf:params:scim:schemas:extension:seoclarity:2.0:User" 
  ], 
  "id": "{UserID}", 
  "userName": "abc@company.com", 
  "urn:ietf:params:scim:schemas:extension:seoclarity:2.0:User": { 
"permission": "sysadmin", 
"domainIdList": [4, 256] 
  } 
} 
Notes: 
  1. Id: {UserID} is an internal seoClarity ID that is returned as a part of response. This is used for other APIs for different operations. 

Update A User

method: PUT 
Authorization header: access_token 

Note: “Replace” is the only supported operation. It supports replacing any field specified during Creating user EXCEPT for Username (email address). 

Request Sample:
{ 
  "schemas": [ 
"urn:ietf:params:scim:api:messages:2.0:PatchOp" 
  ], 
  "Operations": [ 
{ 
   "op": "replace", 
   "path": "urn:ietf:params:scim:schemas:extension:seoclarity:2.0:User", 
   "value": [ 
     { 
       "name": "domainIdList", 
       "values": [ 
         256 
       ] 
     } 
   ] 
}, 
{ 
   "op": "replace", 
   "path": "name", 
   "value": { 
     "givenName": "abc", 
     "familyName": "def" 
   } 
} 
  ] 
                            } 

Get a Single User

method: GET 
Authorization header: access_token 
Request Sample:  api.seoclarity.net/seoClarity/scim/users/1234 

{ 
  "schemas": [ 
"urn:ietf:params:scim:schemas:core:2.0:User", 
"**urn:ietf:params:scim:schemas:extension:seoclarity:2.0:User**" 
  ], 
  "userName": "abc@company.com", 
  "company": "companyName", 
  "name": { 
"familyName": "Scim", 
"givenName": "User" 
  }, 
“id": "1234", 
  "active": true, 
  "urn:ietf:params:scim:schemas:extension:seoclarity:2.0:User": { 
"permission": "sysadmin", 
"domainIdList": [4,256] 
  } 
} 

Delete A User

method: DELETE 
Authorization header: access_token 
Request Sample: api.seoclarity.net/seoClarity/scim/users/1234 

List all Users

method: GET 
Authorization header: access_token 
Sample Request: api.seoclarity.net/seoClarity/scim/users 
Sample Request Pagination: api.seoclarity.net/seoClarity/scim/users?startIndex=1&count=10 
Sample Request pagination with filters: api.seoclarity.net/seoClarity/scim/users?startIndex=1&count=10&filter={filters} 

Attribute 
Requirement 
Description 
Example 
startIndex 
n 
for pagination, default value is 1, first page 
 
count 
n 
for pagination, default value is 10. maximum value is 100. 
 
filter 
n 
filter by userName 
JSON 

Filters 
{ 
  "filters": [ 
{ 
   "name": "userName", 
   "operation": "ew", 
   "value": "['gmail.com','seoclarity.com']" 
} 
  ] 
} 
Notes: Filter is only allowed with "userName" 
 
Available Filter Options:

Value 
Description 
Note 
eq 
equal to 
support array query 
neq 
not equal to 
support array query 
ct 
contain 
 
nct 
not contain 
 
re 
regex (Regular expression) 
 
nre 
regex not match 
 
sw 
start with 
 
ew 
end with 
 

Sample Response:
Sample Response 
{ 
  "schemas": [ 
"urn:ietf:params:scim:api:messages:2.0:ListResponse" 
  ], 
  "totalResults": 200, 
  "itemsPerPage": 10, 
  "startIndex": 1, 
  "resources": [ 
{ 
   "schemas": [ 
     "urn:ietf:params:scim:schemas:core:2.0:User", 
     "urn:ietf:params:scim:schemas:extension:seoclarity:2.0:User" 
   ], 
   "userName": "abc@company.com", 
   "company": "companyName", 
   "name": { 
     "familyName": "abc", 
     "givenName": "User" 
   }, 
   "id": "1234", 
   "active": true, 
   "urn:ietf:params:scim:schemas:extension:seoclarity:2.0:User": { 
     "permission": "sysadmin", 
     "domainIdList": [ 
       4, 
       256 
     ] 
   } 
}, 
{ 
   "schemas": [ 
     "urn:ietf:params:scim:schemas:core:2.0:User", 
     "urn:ietf:params:scim:schemas:extension:seoclarity:2.0:User" 
   ], 
   "userName": "def@company.com", 
   "company": "companyName", 
   "name": { 
     "familyName": "def", 
     "givenName": "User" 
   }, 
   "id": "45676", 
   "active": true, 
   "urn:ietf:params:scim:schemas:extension:seoclarity:2.0:User": { 
     "permission": "sysadmin", 
     "domainIdList": [ 
       4661 
     ] 
   } 
} 
  ] 
} 

API Usage

Description:API Token Usage Report (private, for more details, please access /help/usage)
Cost: Free
Request Format:
Parameters:
  1. Access_token
    1. The access_token is a long string of letters and numbers that you include in API calls to let us know what user you are making the API call and what permissions your app has for that user
  2. sDate
    1. Query Start date
    2. Format is yyyymmdd
    3. Example: 20140501
    4. Parameter cannot be null
  3. eDate
    1. Query End date

    2. Format is yyyyymmdd
    3. Example: 20140502
    4. Parameter cannot be null
  4. Group
    1. Group results by day, week or month.
    2. Default value is month, group=day or group=week or group=month
    3. Parameter can be null

Sample Response
<commands>
<command>
<commandName>event</commandName>
<date>
<day>2014-09-18</day>
<count>7</count>
</date>
</command>
<command>
<commandName>keyword</commandName>
<date>
<day>2014-09-18</day>
<count>6</count>
</date>
</command>
…
…
…
</commands>

Support

In case of any issues or questions related to the API, please contact the client success team at support@seoclarity.net .


    • Related Articles

    • What is an API?

      API stands for Applications Program Interface which is a set of protocols or routines in order to share data. Each call queries a certain set of data based on the tasks it is supposed to accomplish. The API acts almost as a translator of ...

    • How do I generate an API Token?

      To generate an API Token, you must have admin access and navigate to the Integrations tab of the Settings page. On this page, select the API access card to generate an API Token for your login. After generating the token, it will appear here. Find ...

    • Adobe Analytics Data Differences

      Adobe Analytics Integration Methods The preferred Adobe Analytics integration method for seoClarity is via Adobe's API (Partner Exchange Integration). The API allows for dimensions like search engine, device, and landing page data to be provided. If ...

    • IBM Coremetrics Data Differences

      Integration Methods          Explore            The preferred Coremetrics integration method for seoClarity is the Explore reports. This is preferred because these reports include all 3 elements we need to complete the analytics integration - ...

    • seoClarity.dev API Data

      seoClarity.dev is an add-on feature that can be enabled by request via your Client Success Manager or support@seoclarity.net. Get access to the same data ocean and core capabilities that power the seoClarity.net platform. Build your own tools, ...