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. | |
| 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.
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
}
}