1. Help
  2. Links API
  3. Making Calls With Links API V2
  4. Link Intersect

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.

What's Covered?

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

Use this endpoint to get 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.

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

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 Access ID and Secret Key within your Moz Account.

Just a reminder - the Links API V2 supports Basic Auth in which you are able to use your Access ID as a username and and your Secret Key as a password.

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)

Related Articles

Was this article helpful?

Happy Yes! Amazing! Satisfied Yes! It was what I needed. Neutral Meh. It wasn’t really what I was looking for. Sad No, it wasn’t helpful at all.

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.