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

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