1. Help
  2. Moz API
  3. V2 API Endpoint Documentation
  4. V2 Link Intersect

V2 Link Intersect

Frequently Asked Questions

  • This endpoint’s data will be counted as a 5x multiplier for every row returned (where each row represents an “intersecting” link, i.e. a source page that has links to all of the URLs passed in the request). Please see here for more information on weighted endpoints.
Have you heard? We've launched a brand new set of Moz API beta endpoints, including Keyword Suggestions, Search intent, Brand AuthorityTM, and more! To learn more and get started, check out the all-new documentation here.

What's Covered?

In this guide you’ll learn more about making API calls to the Link Intersect endpoint for the Moz API V2.

This documentation specifies information for Moz API V2. V1 of the Moz API does not include a Link Intersect endpoint.

What is this endpoint for?

The Link Intersect endpoint will return data about sites that are linking to your competitors, but not to you. This is a clever way to explore your competitors’ backlink profile, and gives you some helpful ideas about which sites you may want to reach out to when performing your link building outreach. The endpoint works by providing a list of sources that link to at least one of a list of positive targets and don't link to any of a list of negative targets. The data for this endpoint is similar to what is returned in the Link Intersect section of Link Explorer.

Please note: This is a weighted endpoint which means that data returned from this endpoint will count as more than 1 row consumed when data is requested. Please see here for more information on weighted endpoints.

Quick Links

Getting Started

Before making calls to the Link Intersect 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 Link Intersect data from Links V2, be sure to use the following endpoint.

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

Request Syntax

          
{
    "positive_targets": [{
        "target": "string",
        "scope": "string"
    }],
    "negative_targets": [{
        "target": "string",
        "scope": "string"
    }],
    "min_matching_targets": number,
    "source_scope": "string",
    "sort": "string",
    "limit": number,
    "next_token": "string"
}

Example JSON Request

          
{
    "positive_targets": [{
            "target": "latimes.com",
            "scope": "root_domain"
        },
        {
            "target": "blog.nytimes.com",
            "scope": "subdomain"
        }
    ],
    "negative_targets": [{
        "target": "moz.com",
        "scope": "root_domain"
    }],
    "source_scope": "page",
    "sort": "source_domain_authority",
    "limit": 1
}

Request Parameters

"positive_targets" - Get sources that link to at least one of these positive targets. Up to 6 total targets may be specified in the 'positive_targets' and 'negative_targets' fields (combined).

  • Type: Array of Map objects
  • Required: yes
  • When indicating “positive_targets”:
    • "target" - The url for this target.
      • Type: string
      • Required: yes
    • "scope" - Find sources that link to 'target' at this scope.
      • Type: string
      • Required: yes

"negative_targets" - Get sources that don't link to any of these negative targets. Up to 6 total targets may be specified in the 'positive_targets' and 'negative_targets' fields (combined).

  • Type: Array of string objects
  • Required: no
  • When indicating “negative_targets”:
    • "target" - The url for this target.
      • Type: string
      • Required: yes
    • "scope" - Find sources that don't link to 'target' at this scope.
      • Type: string
      • Required: yes

"min_matching_targets" - If set, only results that match at least this many positive targets will be returned.

  • Type: number
  • Required: no

"source_scope" - The scope of sources to return. The default value is 'page'.

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

"sort" - The order to return results in. Results are returned in descending order (higher values first). The default value is 'matching_target_count'.

  • Type: string
  • Required: no
  • Valid Values: source_domain_authority, source_spam_score, matching_target_count

"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

Response Syntax

          
{
    "results": [{
        "page": "string",
        "title": "string",
        "domain_authority": number,
        "spam_score": number,
        "matching_target_indexes": [number],
        // Only present if input parameter 'source_scope' == 'root_domain'
        "matching_source_pages": [{
            "page": "string",
            "page_authority": number
        }]
    }],
    "next_token": "string"
}

Example JSON Response

          
{
   "results": [
       {
           "page": "www.google.com/amp/www.latimes.com/business/hollywood/la-fi-ct-espn-streaming-20170810-story,amp.html",
           "title": "",
           "domain_authority": 100,
           "spam_score": 15,
           "matching_target_indexes": [
               0
           ]
       }
   ],
   "next_token": "Ao3225XIVYho"
}

Response Elements

"results"- An array of sources that satisfy the request.

  • Type: Array of Map objects
  • Within “results” the following response elements exist:
    • "page" - The url of the source, after canonicalization.
      • Type: string
    • "title" - If the 'source_scope' request parameter is 'page', the title of the source page seen the most recent time it has been crawled. If the 'source_scope' request parameter is 'root_domain', this element will always be blank.
      • Type: string
    • "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
    • "spam_score" - The spam score for the source, or -1 if a spam score does not exist for that source.
      • Type: number
    • "matching_target_indexes" - An array of indexes into the 'positive_targets' request parameter, with one entry for each positive target this source links to. The values in this array are sorted in ascending numeric order.
      • Type: Array of numbers
    • "matching_source_pages" - If request parameter 'source_scope' is set to 'root_domain', this element aligns with the 'matching_target_indexes' field and contains the highest page-authority URL from this source that links to each target. If request parameter 'source_scope' is set to 'page', this element will be empty.
      • Type: Array of Map objects
      • Within “matching_source_pages” the following response elements exist:
        • "page" - The source page, after canonicalization.
          • Type: string
        • "page_authority" - A score from 1 to 100 representing the likelihood that this page will rank well in search engine result pages.
          • Type: number

"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

  • Up to 500 results for all types of queries. (50 per request)
  • For queries including positive and/or negative targets with more than 100,000 linking pages, some low-quality sources may not be 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/link_intersect
Host: lsapi.seomoz.com
Content-Length: [length of request payload in bytes]
User-Agent: [user agent string]
Authorization: Basic [credentials]
{
    "positive_targets": [{
            "target": "latimes.com",
            "scope": "root_domain"
        },
        {
            "target": "blog.nytimes.com",
            "scope": "subdomain"
        }
    ],
    "negative_targets": [{
        "target": "moz.com",
        "scope": "root_domain"
    }],
    "source_scope": "page",
    "sort": "source_domain_authority",
    "limit": 1
}

Example cURL Request

          
curl -d '{"positive_targets": [{"target": "latimes.com", "scope": "root_domain"}, {"target": "http://blog.nytimes.com ", "scope":"subdomain"}], "negative_targets": [{"target": "moz.com", "scope": "root_domain"}], "source_scope": "page", "sort": "source_domain_authority", "limit": 1}' -X POST https://lsapi.seomoz.com/v2/link_intersect -u 'access_id:secret_key'

Example Python Request

          
import requests
auth = (access_id, secret_key)
url = "https://lsapi.seomoz.com/v2/link_intersect"
data = """{
        "positive_targets": [{
                        "target": "latimes.com",
                        "scope": "root_domain"
                    },
                    {
                        "target": "blog.nytimes.com",
                        "scope": "subdomain"
                    }],
        "negative_targets": [{
                        "target": "moz.com",
                        "scope": "root_domain"
                    }],
        "source_scope": "page",
        "sort": "source_domain_authority",
        "limit": 1
    }"""
request = requests.post(url, data=data, auth=auth)

Was this article helpful?

Thanks for the feedback.

Contact the Help Team if you have a specific question.
Cancel

Woo! 🎉
Thanks for the feedback.

Got it.
Thanks for the feedback.