Obtaining the list of domains from top 20 project keywords

The RtApiSerpResultsProcedure.getTopCompetitorsDomainsHistory method returns the list of domains for the required region, which were listed in the top-20 for two any project keywords. The data set is similar to the Rank tracker  Competitors report.

General request parameters and instructions for using Serpstat API

Request parameters

Parameter

Description

Type

Optional

Default value

Value options

id

A request id: the response contains the same id.

int/string

no

Any text or number value.
For example: 1, test

method

API method name

string

no

RtApiSerpResultsProcedure.getTopCompetitorsDomainsHistory

params

The object with parameters {...}, it lists all the following parameters and arrays [...]

no

projectId Project ID int no Number value of project
projectRegionId Region ID int no Number value of region
page Page number int no 1 Number value
pageSize Number of results per page int yes 100 Number value. Possible values: 20, 50, 100, 200, 500
dateFrom Start date of the period for which the data is required date yes 30 days from the last position withdrawal Number value, data format: yyyy-mm-dd
dateTo End date of the period for which the data is required date yes Date of last withdrawal of positions Number value, data format: yyyy-mm-dd
sort Sorting by parameters string yes traffic Possible values:

"sum_traffic" — by traffic distribution,
"keywords_count" — by the number of keywords,
"avg_position" — by average position,
"position_ranges" — by position distribution tops,
"ads_count" — by number of ads
sortRange Possible values:

"top1\top2"... — position distribution by position,
"keywords_count_bottom\keywords_count_top" — distribution by ads,
"avg_position_top\avg_position_bottom" — average position by ads
order Sorting order string yes desc desc — descending order,
asc — ascending order
domains Domain/domains for which the data is required array yes All domains in top 20 for two project keywords Text value.
Data format:
["domain1.com", "domain2.com"]

Response parameters
Parameter Description
id Response id corresponds the request id
result Contains the answer
data Object with data
projectId Project ID
ProjectRegionId Region ID
competitors Array with domains
domain Domain that is appeared in top 20 by two project keyword
dates Array with dates for the specified domain
date Date for which the data of the domain is displayed
value Parameter value
traffic_distribution Domain traffic distribution among all domains in top 20
avg_position Domain average position, among the best positions for project keywords
keywords_count Number of keywords which the domain is ranking for into search results
keywords_by_ranges Keywords distribution by domain position range
top1 Keywords for which the domain took the 1 position
top3 Keywords for which the domain took the 2-3 positions
top5 Keywords for which the domain took the 4-5 positions
top10 Keywords for which the domain took the 6-10 positions
top20 Keywords for which the domain took the 11-20 positions
top101 Keywords for which the domain took the 21-100 positions in Google
Regions with PPC
ads_count Number of ads for which domain is appeared in PPC
keywords_count_blocks Keywords distribution by PPC blocks
avg_position_blocks Average position distribution by PPC blocks
top Top ad block
sidebar Side ad block
bottom Bottom ad block
summary info Summary data block
page Current page
page_total Number of pages with the results for the selected parameter pageSize
count Number of results per page
total Total number of results
sort  Sorting by parameters
order   Sorting order

Possible errors in response
Error's code Description
-32009\-32602 Invalid request parameters. Description of parameters with issues and why that happened
-33054 Project deleted
-34001 Invalid projectRegionId for project
-34002 Date range must be have less 30 parsing dates
-32002 Empty result
-34004 Page out of size

Credits for this method are not deducted.

Example
Request data:
{
    "id": "1",
    "method": "RtApiSerpResultsProcedure.getTopCompetitorsDomainsHistory",
   "params": {
        "projectId": 853932,
        "projectRegionId": 293402,
        "page": 1,
        "pageSize": 20,
        "dateFrom": "2021-07-26",
        "dateTo": "2021-07-27",
        "sort": "domain",
        "order": "asc",
        "domains": [
            "adidas.com",
            "nike.com"
        ]  
    }
}
Response data:
{
    "id": "1",
    "result": {
        "data": {
            "projectId": 853932,
            "projectRegionId": 293402,
            "competitors": [
                {
                    "domain": "adidas.com",
                    "dates": [
                        {
                            "date": "2021-07-26",
                            "result": {
                                "traffic_distribution": {
                                    "value": 19.390000000000001
                                },
                                "avg_position": {
                                    "value": 2.7000000000000002
                                },
                                "keywords_count": {
                                    "value": 12
                                },
                                "keywords_by_ranges": {
                                    "top1": {
                                        "value": 5
                                    },
                                    "top3": {
                                        "value": 3
                                    },
                                    "top5": {
                                        "value": 3
                                    },
                                    "top10": {
                                        "value": 1
                                    },
                                    "top20": {
                                        "value": 0
                                    },
                                    "top101": {
                                        "value": 0
                                    }
                                }
                            }
                        },
                        {
                            "date": "2021-07-27",
                            "result": {
                                "traffic_distribution": {
                                    "value": 17.25
                                },
                                "avg_position": {
                                    "value": 3.1000000000000001
                                },
                                "keywords_count": {
                                    "value": 12
                                },
                                "keywords_by_ranges": {
                                    "top1": {
                                        "value": 6
                                    },
                                    "top3": {
                                        "value": 2
                                    },
                                    "top5": {
                                        "value": 2
                                    },
                                    "top10": {
                                        "value": 2
                                    },
                                    "top20": {
                                        "value": 0
                                    },
                                    "top101": {
                                        "value": 0
                                    }
                                }
                            }
                        }
                    ]
                },
                {
                    "domain": "nike.com",
                    "dates": [
                        {
                            "date": "2021-07-26",
                            "result": {
                                "traffic_distribution": {
                                    "value": 7.6299999999999999
                                },
                                "avg_position": {
                                    "value": 15.1
                                },
                                "keywords_count": {
                                    "value": 9
                                },
                                "keywords_by_ranges": {
                                    "top1": {
                                        "value": 0
                                    },
                                    "top3": {
                                        "value": 2
                                    },
                                    "top5": {
                                        "value": 1
                                    },
                                    "top10": {
                                        "value": 3
                                    },
                                    "top20": {
                                        "value": 2
                                    },
                                    "top101": {
                                        "value": 1
                                    }
                                }
                            }
                        },
                        {
                            "date": "2021-07-27",
                            "result": {
                                "traffic_distribution": {
                                    "value": 7.6799999999999997
                                },
                                "avg_position": {
                                    "value": 14.6
                                },
                                "keywords_count": {
                                    "value": 9
                                },
                                "keywords_by_ranges": {
                                    "top1": {
                                        "value": 0
                                    },
                                    "top3": {
                                        "value": 2
                                    },
                                    "top5": {
                                        "value": 1
                                    },
                                    "top10": {
                                        "value": 3
                                    },
                                    "top20": {
                                        "value": 2
                                    },
                                    "top101": {
                                        "value": 1
                                    }
                                }
                            }
                        }
                    ]
                }
            ]
        },
        "summary_info": {
            "page": 1,
            "page_total": 1,
            "count": 20,
            "total": 2,
            "sort": "domain",
            "order": "asc"
        },
        "spent_limits": 0
    }
}

Share this article with your friends

Are you sure?

Introducing Serpstat

Find out about the main features of the service in a convenient way for you!

Please send a request, and our specialist will offer you education options: a personal demonstration, a trial period, or materials for self-study and increasing expertise — everything for a comfortable start to work with Serpstat.

Name

Email

Phone

We are glad of your comment
I agree to Serpstat`s Privacy Policy.

Thank you, we have saved your new mailing settings.

Open support chat