Obtaining the list of pages and their positions by domain
The RtApiSerpResultsProcedure.getUrlsSerpResultsHistory method returns the history of the positions and urls for the keywords to the requested region. The data set is similar to the Rank tracker - Positions 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. |
| domain | Domain or page for which the data is required | string | no | project domain | Text value. Data format: domain.com — domain, https://domain.com/ — page |
| 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 |
| domain | Domain or page for which the search results are requested |
| keywords | Array with keywords |
| keyword | Keyword |
| 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 with dates of search results by 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 |
| positionBlock (only for PPC) | PPC block: * top — top ad block; * sidebar — side ad block; * bottom — bottom ad block |
| 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 |
Request data:
{
"id": 1,
"method": "RtApiSerpResultsProcedure.getUrlsSerpResultsHistory",
"params": {
"projectId": 930722,
"projectRegionId": 309245,
"page": 1,
"pageSize": 500,
"dateFrom": "2023-10-09",
"dateTo": "2023-10-23",
"sort": "date",
"order": "desc",
"keywords": [],
"withTags": false,
"domain": "https://makeup.com.ua/brand/29737/"
}
}Response data:
{
"id": "1",
"result": {
"data": {
"projectId": 930722,
"projectRegionId": 309245,
"domain": "https://makeup.com.ua/brand/29737/",
"keywords": [
{
"keyword": "фрэнчи",
"frequency": 27100,
"expectedUrl": "https://makeup.com.ua/",
"history": [
{
"date": "2023-10-23",
"positions": [
{
"position": 1,
"url": "https://makeup.com.ua/brand/29737/"
}
]
},
{
"date": "2023-10-16",
"positions": [
{
"position": 2,
"url": "https://makeup.com.ua/brand/29737/"
}
]
},
{
"date": "2023-10-09",
"positions": [
{
"position": 2,
"url": "https://makeup.com.ua/brand/29737/"
}
]
}
]
},
{
"keyword": "френчи",
"frequency": 27100,
"expectedUrl": "",
"history": [
{
"date": "2023-10-23",
"positions": []
},
{
"date": "2023-10-16",
"positions": [
{
"position": 2,
"url": "https://makeup.com.ua/brand/29737/"
}
]
},
{
"date": "2023-10-09",
"positions": [
{
"position": 2,
"url": "https://makeup.com.ua/brand/29737/"
}
]
}
]
},
{
"keyword": "главкома",
"frequency": 165000,
"expectedUrl": "",
"history": [
{
"date": "2023-10-23",
"positions": []
},
{
"date": "2023-10-16",
"positions": []
},
{
"date": "2023-10-09",
"positions": []
}
]
},
{
"keyword": "мейкап украина",
"frequency": 0,
"expectedUrl": "https://www.americanhorror.fans/",
"history": [
{
"date": "2023-10-23",
"positions": []
},
{
"date": "2023-10-16",
"positions": []
},
{
"date": "2023-10-09",
"positions": []
}
]
},
{
"keyword": "косметика для всей семьи и не только покупайте и радуйтесь",
"frequency": 0,
"expectedUrl": "",
"history": [
{
"date": "2023-10-23",
"positions": []
},
{
"date": "2023-10-16",
"positions": []
},
{
"date": "2023-10-09",
"positions": []
}
]
},
"summary_info": {
"page": 1,
"page_total": 1,
"count": 500,
"total": 44,
"sort": "date",
"order": "desc"
},
"spent_limits": 0
}
}