Obtaining the search results history in region by keywords
The RtApiSerpResultsProcedure.getKeywordsSerpResultsHistory method returns Google's top-100 search results for the required region and project keywords. The data set is similar to the Rank tracker - SERP history.
Use case: Get the history of search results for certain keyword phrases of a project in a specific region to analyze the dynamics of changes in search results and the effectiveness of the SEO strategy.
1. Use the RtApiSerpResultsProcedure.getKeywordsSerpResultsHistory method to get the search results
history for the project's keywords in the specified region.
2. Get a list of website positions in search results, as well as the history of changes in these positions over time.
3. Use the data to analyze the history of search results: which sites consistently hold high positions, how your
domain's positions in the search results change. Determine what SEO actions you need to take to improve
your results.
General request parameters and instructions for using Serpstat API
Search databases available
Request parameters | |||||
Parameter | Description | Type | Required | Default value | Value options |
id | A request id: the response contains the same id. | int/string | yes | Any text or number value. | |
method | API method name | string | yes | RtApiSerpResultsProcedure.getKeywordsSerpResultsHistory | |
params | The object with parameters {...}, it lists all the following parameters and arrays [...] |
| yes | ||
projectId | Project ID | int | yes | Number value of project | |
projectRegionId | Region ID | int | yes | Number value of region | |
page | Page number | int | yes | 1 | Number value |
pageSize | Number of results per page | int | no | 100 | Number value. Possible values: 20, 50, 100, 200, 500 |
dateFrom | Start date of the period for which the data is required | date | no | All dates of withdrawal of positions | Number value, data format: yyyy-mm-dd |
dateTo | End date of the period for which the data is required | date | no | All dates of withdrawal of positions | Number value, data format: yyyy-mm-dd |
sort | Sorting by parameters | string | no | alphabetically | "date" — Sorting by date, "keyword" — Sorting alphabetically |
order | Sorting order | string | no | desc | desc — descending order, asc — ascending order |
keywords | Keywords for which pages and positions are required | array | no | All keywords of the project | Text value. The maximum number of keywords that can be filtered is 1000. |
withTags | Display tags for the kewords | string | no | false | Text value. "true" or "false" |
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 |
keywords | Array with keywords |
keyword | Keywords with data |
frequency | Search volume per month in the selected country or city |
expectedUrl | A landing page that is optimized for a specific keyword (if it was added in the project) |
tags | Array of tag`s id and value (name of the tag) |
history | Array of dates with search results for keyword |
date | Search results date |
positions | Array with positions of domain or page |
position | Position |
url | A page that appears in search results for a specific keyword |
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 |
-34003 | Keywords not found in project |
-32002 | Empty result |
Credits for this method are not deducted.
{
"id": 1,
"method": "RtApiSerpResultsProcedure.getKeywordsSerpResultsHistory",
"params": {
"projectId": 715910,
"projectRegionId": 262189,
"page": 1,
"pageSize": 500,
"dateFrom": "2020-05-19",
"dateTo": "2020-05-21",
"sort": "date",
"order": "asc",
"keywords": ["1"],
"withTags": true
}
}
{
"id": "test_id",
"result": {
"data": {
"projectId": 715910,
"projectRegionId": 262189,
"keywords": [
{
"keyword": "1",
"frequency": 30,
"expectedUrl": "https://1plus1.video/fungicid-strobi-200-gr-upakovka-instrukciya-primenenienorma.html",
"tags": [
{
"id": "4d94e7e6-e32f-4889-b8e4-ac4142ed1f34",
"value": "other tag"
},
{
"id": "f5acf3a9-d67b-468d-8d36-23eca82b1eb4",
"value": "test tag"
}
]
"history": [
{
"date": "2020-05-21",
"positions": [
{
"position": 1,
"url": "https://1plus1.video/tvguide/1plus1/online"
},
{
"position": 2,
"url": "https://1plus1.video/"
}
]
}
]
}
]
},
"summary_info": {
"page": 1,
"page_total": 1,
"count": 500,
"total": 1,
"sort": "date",
"order": "asc"
}
}
}