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.
Use case: Get a list of pages for a specific domain and their positions in search engines for further analysis and SEO optimization.
1. Use the RtApiSerpResultsProcedure.getUrlsSerpResultsHistory method to get a list of pages for a
domain and their positions in search results for the specified keywords.
2. Get a list of domain pages and their positions for various keywords.
3. Use the data to analyze the best and worst ranking pages of the domain. Analyze which key phrases lead to
these positions and determine which pages need to be optimized or updated with new content.
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 |
Credits for this method are not deducted.
{
"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/"
}
}{
"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
}
}