Linking Root Domains

What's Covered?

In this guide you’ll learn more about making API calls to the Linking Root Domains endpoint for the Links API V2.

This documentation specifies information for Moz Links API V2. V1 of the Links API does not include a Linking Root Domains endpoint.

What is this endpoint for?

Use this endpoint to get a list of linking root domains to a target. In other words, this endpoint returns a list of the sites linking to your site or page. You can use this data to monitor link building campaign progress or to do competitive research. For reference, if you have ten backlinks from a single domain, like Pinterest or Wikipedia, this will be counted as one linking domain. This endpoint will also return how many pages on the site are linking to your target URL. The data from this endpoint is similar to the data seen in the Linking Domains section of Link Explorer.

Quick Links

Getting Started

Before making calls to the Linking Root Domains endpoint, be sure you are set up with an API token within your Moz Account.

For information regarding authentication, please see our Overview & Authentication guide.

All requests and responses are structured in JSON.

Endpoint Location

When requesting linking root domains data from Links V2, be sure to use the following endpoint.

          
https://lsapi.seomoz.com/v2/linking_root_domains
        

Request Syntax

          
{
    "target": "string",
    "target_scope": "string",
    "sort": "string",
    "filter": "string",
    "begin_date": "string",
    "end_date": "string",
    "limit": number,
    "next_token": "string
}
        

Example JSON Request

          
{
    "target": "moz.com/blog",
    "target_scope": "page",
    "filter": "external",
    "sort": "source_domain_authority",
    "limit": 1
}
        

Request Parameters

"target" - A URL to get linking root domains for.

  • Type: string
  • Required: yes

"target_scope" - Find links to 'target' at this scope. The default value is 'page'.

  • Type: string
  • Required: no
  • Valid Values: page, subdomain, root_domain

"sort" - The order to return linking root domains in. The default value is 'source_domain_authority'. Results are returned in descending order (higher values first). For date sorts, more recent results are returned first.

"filter" - Only return linking root domains that match this filter. The default value is 'external'. Multiple filters can be combined into an expression using the '+' symbol (for example, 'external+follow'). Positive filters require at least one matching link from the source root domain, and negative filters require all links to match -- for example, the 'follow' filter requires at least one followed link from the source domain to the target, but the 'nofollow' filter requires all links from the source domain to the target to be nofollow links.

"begin_date" - This parameter can only be used when 'sort' is 'date_gained' or 'date_lost', and restricts results to only those gained or lost on or after this date. Values must be in YYYY-MM-DD form.

  • Type: string
  • Required: no

"end_date" - This parameter can only be used when 'sort' is 'date_gained' or 'date_lost', and restricts results to only those gained or lost on or before this date. Values must be in YYYY-MM-DD form.

  • Type: string
  • Required: no

"limit" - Only return up to this number of results. The default value is 25.

  • Type: number
  • Required: no
  • Valid Values: 1-50

"next_token" - If set, return the next set of results from a previous request whose 'next_token' element equals this value.

  • Type: string
  • Required: no

Parameter Compatibility

The following combinations of request parameters are valid:

begin_dateend_datesortfilter
unsetunsetsource_domain_authority, source_link_propensity, source_spam_scoreexternal, external + [ follow | nofollow | deleted | not_deleted ]
eithereitherdate_gainedexternal + gained_last_60_days
eithereitherdate_lostexternal + lost_last_60_days

Response Syntax

          
{
    "results": [{
        "root_domain": "string",
        "root_domains_to_root_domain": number,
        "domain_authority": number,
        "link_propensity": number,
        "spam_score": number,
        "to_target": {
            "pages": number,
            "nofollow_pages": number,
            "redirect_pages": number,
            "deleted_pages": number
        },
        // Only present if input parameter 'filter' includes
        // 'gained_last_60_days'
        "date_gained": "string",
        // Only present if input parameter 'filter' includes
        // 'lost_last_60_days'
        "date_lost": "string"
    }],
    "next_token": "string"
}
        

Example JSON Response

          
{
   "results": [
       {
           "root_domain": "linkedin.com",
           "root_domains_to_root_domain": 9456093,
           "domain_authority": 99,
           "link_propensity": 0.05133872479,
           "spam_score": 1,
           "to_target": {
               "pages": 4,
               "nofollow_pages": 4,
               "redirect_pages": 0,
               "deleted_pages": 0
           }
       }
   ],
   "next_token": "IokQVg4s9ak8iRBWDiz1qTyguYswnj035py4NnkPmfc4lQAUqQJLMpMvuw=="
}
        

Response Elements

"results" - An array of linking root domains to 'target'.

  • Type: Array of Map objects
  • Within “results” the following response elements exist:
    • "root_domain" - The source root domain for this result.
      • Type: string
    • "root_domains_to_root_domain" - The number of unique root domains currently linking to the source root domain.
      • Type: number
    • "domain_authority" - A score from 1 to 100 representing the likelihood that the source root domain will rank well in search engine result pages.
      • Type: number
    • "link_propensity" - A score from 0 to 1 indicating the likelihood of the source root domain to link out to other root domains. This is currently calculated as the ratio of 'root_domains_from_root_domain' to 'pages_crawled_from_root_domain'.
      • Type: number
    • "spam_score" - The spam score for the source root domain, or -1 if a spam score does not exist for that root domain.
      • Type: number
    • "to_target" - A map of link counts from the source root domain to the target.
      • Type: Map object
      • Within “to_target” the following response elements exist:
        • "pages" - The number of pages on the source root domain currently linking to the target.
          • Type: number
        • "nofollow_pages" - The number of pages on the source root domain currently linking to the target with only nofollow links.
          • Type: number
        • "redirect_pages" - The number of pages on the source root domain currently redirecting to the target.
          • Type: number
        • "deleted_pages" - The number of pages on the source root domain that used to link to the target, but no longer do.
          • Type: number
        • "date_gained" - The date the source root domain started linking to the target, in 'YYYY-MM-DD' format.
          • Type: string
        • "date_lost" - The date the source root domain stopped linking to the target, in 'YYYY-MM-DD' format.
          • Type: string

"next_token" - If non-empty, the number of results was limited by the 'limit' parameter, and the next set of results can be obtained by repeating the request with the 'next_token' request parameter set to this value.

  • Type: string

Limits

  • When sort is 'source_domain_authority' and no filter is in effect, there are no limits (i.e. it's possible to iterate through all linking root domains to a target).
  • Otherwise, at most 10,000 linking root domains are returned.

Errors

See the Common Errors section for errors that are common to all endpoints.

          
Gone
Message: The next token has expired
HTTP Status code: 410
        

Example HTTP Request

          
POST /v2/linking_root_domains
Host: lsapi.seomoz.com
Content-Length: [length of request payload in bytes]
User-Agent: [user agent string]
Authorization: Basic [credentials]
{
    "target": "moz.com/blog",
    "target_scope": "page",
    "filter": "external",
    "sort": "source_domain_authority",
    "limit": 1
}
        

Example cURL Request

          
curl -d  '{"target": "moz.com/blog", "target_scope": "page", "filter": "external", "sort": "source_domain_authority", "limit": 1}' -X POST https://lsapi.seomoz.com/v2/linking_root_domains -u 'access_id:secret_key'
        

Example Python Request

          
import requests
auth = (access_id, secret_key)
url = "https://lsapi.seomoz.com/v2/linking_root_domains"
data = """{
        "target": "moz.com/blog",
        "target_scope": "page",
        "filter": “external",
        "sort": "source_domain_authority",
        "limit": 5
    }"""
request = requests.post(url, data=data, auth=auth)
        

Related Articles


Woo! 🎉
Thanks for the feedback.

Got it.
Thanks for the feedback.