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