This endpoint will provide you with the list of domains pointing to the specified websites. This endpoint is especially useful for creating a Link Gap feature that shows what domains link to your competitors but do not link out to your website.
Instead of ‘login’ and ‘password’ use your credentials from https://app.dataforseo.com/api-dashboard
<?php
// You can download this file from here https://cdn.dataforseo.com/v3/examples/php/php_RestClient.zip
require('RestClient.php');
$api_url = 'https://api.dataforseo.com/';
// Instead of 'login' and 'password' use your credentials from https://app.dataforseo.com/api-dashboard
$client = new RestClient($api_url, null, 'login', 'password');
$post_array = array();
// simple way to set a task
$post_array[] = array(
"targets" => [
"1" => "moz.com",
"2" => "ahrefs.com"
],
"exclude_targets" => [
"semrush.com"
],
"limit" => 5,
"include_subdomains" => false,
"exclude_internal_backlinks" => true,
"order_by" => [
"1.backlinks,desc"
]
);
try {
// POST /v3/backlinks/domain_intersection/live
$result = $client->post('/v3/backlinks/domain_intersection/live', $post_array);
print_r($result);
// do something with post result
} catch (RestClientException $e) {
echo "n";
print "HTTP code: {$e->getHttpCode()}n";
print "Error code: {$e->getCode()}n";
print "Message: {$e->getMessage()}n";
print $e->getTraceAsString();
echo "n";
}
$client = null;
?>
from client import RestClient
# You can download this file from here https://cdn.dataforseo.com/v3/examples/python/python_Client.zip
client = RestClient("login", "password")
post_data = dict()
# simple way to set a task
post_data[len(post_data)] = dict(
targets={
"1":"moz.com",
"2":"ahrefs.com"
},
exclude_targets=[
"semrush.com"
],
limit=5,
include_subdomains=False,
exclude_internal_backlinks=True,
order_by=[
"1.backlinks,desc"
]
)
# POST /v3/backlinks/domain_intersection/live
response = client.post("/v3/backlinks/domain_intersection/live", post_data)
# you can find the full list of the response codes here https://docs.dataforseo.com/v3/appendix/errors
if response["status_code"] == 20000:
print(response)
# do something with result
else:
print("error. Code: %d Message: %s" % (response["status_code"], response["status_message"]))
using Newtonsoft.Json;
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
namespace DataForSeoDemos
{
public static partial class Demos
{
public static async Task backlinks_domain_intersection_live()
{
var httpClient = new HttpClient
{
BaseAddress = new Uri("https://api.dataforseo.com/"),
// Instead of 'login' and 'password' use your credentials from https://app.dataforseo.com/api-dashboard
DefaultRequestHeaders = { Authorization = new AuthenticationHeaderValue("Basic", Convert.ToBase64String(Encoding.ASCII.GetBytes("login:password"))) }
};
var postData = new List<object>();
Dictionary<string, string> pagesDictionary = new Dictionary<string, string>
{
{ "1", "moz.com" },
{ "2", "ahrefs.com" }
};
// simple way to get a result
postData.Add(new
{
targets = pagesDictionary,
exclude_targets = new object[] {
"semrush.com"
},
limit = 5,
order_by = new object[] {
"1.backlinks,desc"
},
include_subdomains = false,
exclude_internal_backlinks = true
});
// POST /v3/backlinks/domain_intersection/live
// the full list of possible parameters is available in documentation
var taskPostResponse = await httpClient.PostAsync("/v3/backlinks/domain_intersection/live", new StringContent(JsonConvert.SerializeObject(postData)));
var result = JsonConvert.DeserializeObject<dynamic>(await taskPostResponse.Content.ReadAsStringAsync());
// you can find the full list of the response codes here https://docs.dataforseo.com/v3/appendix/errors
if (result.status_code == 20000)
{
// do something with result
Console.WriteLine(result);
}
else
Console.WriteLine($"error. Code: {result.status_code} Message: {result.status_message}");
}
}
}
The above command returns JSON structured like this:
All POST data should be sent in the JSON format (UTF-8 encoding). The task setting is done using the POST method. When setting a task, you should send all task parameters in the task array of the generic POST array. You can send up to 2000 API calls per minute. The maximum number of requests that can be sent simultaneously is limited to 30.
You can specify the number of results you want to retrieve, filter and sort them.
Below you will find a detailed description of the fields you can use for setting a task.
Description of the fields for setting a task:
Field name
Type
Description
targets
object
domains, subdomains or webpages to get links for required field
you can set up to 20 domains, subdomains or webpages
a domain or a subdomain should be specified without https:// and www.
a page should be specified with absolute URL (including http:// or https://)
example: "targets": {
"1": "http://planet.postgresql.org/",
"2": "http://gborg.postgresql.org/"
}
exclude_targets
array
domains, subdomains or webpages you want to exclude
optional field
you can specify up to 10 domains, subdomains or webpages
if you use this array, results will contain the referring domains that link to targets but don’t link to exclude_targets
example: "exclude_targets": [
"bbc.com",
"https://www.apple.com/iphone/*",
"https://dataforseo.com/apis/*"]
filters
array
array of results filtering parameters
optional field you can add several filters at once (8 filters maximum)
you should set a logical operator and, or between the conditions
the following operators are supported: regex, not_regex, =, <>, in, not_in, like, not_like, ilike, not_ilike
you can use the % operator with like and not_like to match any string of zero or more characters
example: ["1.internal_links_count",">","1"]
The full list of possible filters is available here.
order_by
array
results sorting rules
optional field
you can use the same values as in the filters array to sort the results
possible sorting types: asc – results will be sorted in the ascending order desc – results will be sorted in the descending order
you should use a comma to set up a sorting type
example: ["backlinks,desc"] note that you can set no more than three sorting rules in a single request
you should use a comma to separate several sorting rules
example: ["backlinks,desc","rank,asc"]
offset
integer
offset in the array of returned results
optional field
default value: 0
if you specify the 10 value, the first ten backlinks in the results array will be omitted and the data will be provided for the successive backlinks
limit
integer
the maximum number of returned results
optional field
default value: 100
maximum value: 1000
internal_list_limit
integer
maximum number of elements within internal arrays
optional field
you can use this field to limit the number of elements within the following arrays: referring_links_tld referring_links_types referring_links_attributes referring_links_platform_types referring_links_semantic_locations
default value: 10
maximum value: 1000
backlinks_status_type
string
set what backlinks to return and count
optional field
you can use this field to choose what backlinks will be returned and used for aggregated metrics for your targets;
possible values: all – all backlinks will be returned and counted; live – backlinks found during the last check will be returned and counted; lost – lost backlinks will be returned and counted;
default value: live
backlinks_filters
array
filter the backlinks of your target
optional field
you can use this field to filter the initial backlinks that will be included in the dataset for aggregated metrics for your target
you can filter the backlinks by all fields available in the response of this endpoint
using this parameter, you can include only dofollow backlinks in the response and create a flexible backlinks dataset to calculate the metrics for
example: "backlinks_filters": [["dofollow", "=", true]]
include_subdomains
boolean
indicates if the subdomains of the target will be included in the search
optional field
if set to false, the subdomains will be ignored
default value: true
include_indirect_links
boolean
indicates if indirect links to the targets will be included in the results
optional field
if set to true, the results will include data on indirect links pointing to a page that either redirects to a target, or points to a canonical page
if set to false, indirect links will be ignored
default value: true
exclude_internal_backlinks
boolean
indicates whether the backlinks from subdomains of the target are excluded
optional field
if set to false, the backlinks from subdomains of the target will be omitted and you won’t receive the same domain in the response;
default value: true
intersection_mode
string
indicates whether to intersect backlinks
optional field
use this field to intersect or merge results for the specified domains
possible values: all, partial all – results are based on all backlinks; partial – results are based on the intersecting backlinks only;
default value: all
tag
string
user-defined task identifier
optional field the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response
As a response of the API server, you will receive JSON-encoded data containing a tasks array with the information specific to the set tasks.
Description of the fields in the results array:
Field name
Type
Description
version
string
the current version of the API
status_code
integer
general status code
you can find the full list of the response codes here Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions
status_message
string
general informational message
you can find the full list of general informational messages here
time
string
execution time, seconds
cost
float
total tasks cost, USD
tasks_count
integer
the number of tasks in the tasks array
tasks_error
integer
the number of tasks in the tasks array returned with an error
tasks
array
array of tasks
id
string
task identifier unique task identifier in our system in the UUID format
status_code
integer
status code of the task
generated by DataForSEO; can be within the following range: 10000-60000
you can find the full list of the response codes here
status_message
string
informational message of the task
you can find the full list of general informational messages here
time
string
execution time, seconds
cost
float
cost of the task, USD
result_count
integer
number of elements in the result array
path
array
URL path
data
object
contains the same parameters that you specified in the POST request
result
array
array of results
targets
object
target domains, subdomains or webpages in a POST array
total_count
integer
total amount of results relevant to your request
items_count
integer
the number of results returned in the items array
items
array
contains domain that link to all targets from the POST array
domain_intersection
object
contains data on domains that link to the corresponding targets specified in the POST array
data is provided in separate objects corresponding to domains, subdomains or pages specified in the targets object
1
object
contains data on a domain that links to the corresponding target from the POST array
field name varies in the range from 1 to 20 according to the number of domains, subdomains, or pages in the targets object
type
string
type of element = ‘backlinks_domain_intersection’
target
string
domain that links to the corresponding target from the POST array
rank
integer
rank referred to the target from the POST array
indicates the rank that the referring domain (target above) refers to your target from the POST array; rank is calculated based on the method for node ranking in a linked database – a principle used in the original Google PageRank algorithm
learn more about the metric and how it is calculated in this help center article
backlinks
integer
indicates the number of backlinks
first_seen
string
date and time when our crawler found the backlink from this target for the first time
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example: 2019-11-15 12:57:46 +00:00
lost_date
integer
date and time when the last backlink from this target was lost
indicates the date and time when our crawler visited the page and it responded with 4xx or 5xx status code or the last backlink was removed
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”
example: 2019-11-15 12:57:46 +00:00
backlinks_spam_score
integer
average spam score of the backlinks pointing to the target
learn more about how the metric is calculated on this help center page
broken_backlinks
integer
number of broken backlinks
broken_pages
integer
number of broken pages
referring_domains
integer
number of referring domains
referring_domains_nofollow
integer
number of domains pointing at least one nofollow link to the corresponding target
referring_main_domains
integer
number of referring main domains
referring_main_domains_nofollow
integer
number of main domains pointing at least one nofollow link to the target
referring_ips
integer
number of referring IP addresses
referring_subnets
integer
number of referring subnetworks
referring_pages
integer
indicates the number of pages pointing to the target
referring_links_tld
object
top level domains of the referring links
contains top-level domains and referring link count per each
referring_links_types
object
types of the referring links
indicates the types of referring links and link count per each type
possible values: anchor, image, link, meta, canonical, alternate, redirect
referring_links_attributes
object
link attributes of the referring links
indicates link attributes of the referring links and the link count per each attribute
referring_links_platform_types
object
types of referring platforms
indicates referring platform types and link count per each platform
referring_links_semantic_locations
object
semantic locations of the referring links
indicates semantic elements in HTML where the referring links are located and the link count per each semantic location
you can get the full list of semantic elements here
referring_links_countries
object
ISO country codes of the referring links
indicates ISO country codes of the domains where the referring links are located and the link count per each country
referring_pages_nofollow
integer
number of referring pages pointing at least one nofollow link to the target