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.

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. For example: 1, test, тест
method	API method name	string	no		RtApiSerpResultsProcedure.getKeywordsSerpResultsHistory
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		Number value, data format: yyyy-mm-dd
dateTo	End date of the period for which the data is required	date	yes		Number value, data format: yyyy-mm-dd
sort	Sorting by parameters	string	yes	alphabetically	"date" — Sorting by date, "keyword" — Sorting alphabetically
order	Sorting order	string	yes	desc	desc — descending order, asc — ascending order
keywords	Keywords for which pages and positions are required	array	yes		Text value. The maximum number of keywords that can be filtered is 1000.

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)
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

This method doesn't require API credits.

Example

Request data:

{
    "id": 1,
    "method": "RtApiSerpResultsProcedure.getKeywordsSerpResultsHistory",
    "params": {
        "projectId": 853932,
        "projectRegionId": 293402,
        "page": 1,
        "pageSize": 100,
        "dateFrom": "2021-12-11",
        "dateTo": "2021-12-12",
        "sort": "date",
        "order": "asc",
        "keywords": ["adidas track"]
    }
}

Response data:

{
    "id": "1",
    "result": {
        "data": {
            "projectId": 853932,
            "projectRegionId": 293402,
            "keywords": [
                {
                    "keyword": "adidas track",
                    "frequency": 49500,
                    "expectedUrl": "https://www.adidas.com/us/track",
                    "history": [
                        {
                            "date": "2021-12-11",
                            "positions": [
                                {
                                    "position": 1,
                                    "url": "https://www.adidas.com/us/track"
                                },
                                {
                                    "position": 2,
                                    "url": "https://www.adidas.com/us/track_suits"
                                },
                                {
                                    "position": 3,
                                    "url": "https://www.adidas.com/us/track_field"
                                },


...


                                {
                                    "position": 95,
                                    "url": "https://www.ispot.tv/ad/oI7z/adidas-worn-without-care-featuring-jay-rock"
                                }
                            ]
                        },
                        {
                            "date": "2021-12-12",
                            "positions": [
                                {
                                    "position": 1,
                                    "url": "https://www.adidas.com/us/track"
                                },
                                {
                                    "position": 2,
                                    "url": "https://www.adidas.com/us/track_suits"
                                },
                                {
                                    "position": 3,
                                    "url": "https://www.adidas.com/us/track_field"
                                },

...

                                {
                                    "position": 96,
                                    "url": "https://www.journeys.com/track-order"
                                }
                            ]
                        }
                    ]
                }
            ]
        },
        "summary_info": {
            "page": 1,
            "page_total": 1,
            "count": 100,
            "total": 1,
            "sort": "date",
            "order": "asc"
        },
        "spent_limits": 0
    }
}