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. For example: 1, test, тест
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.

Example

Request data:

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

Response data:

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