Отримання історії пошукової видачі у регіоні за ключовими фразами проєкту

Метод RtApiSerpResultsProcedure.getKeywordsSerpResultsHistory повертає топ-100 результатiв пошукової видачi Google у вибраному регіоні за ключовими фразами проєкту. Метод доступний тільки для органічної видачі. Аналогічний до звіту Моніторинг позицій - Історія видачі.

Приклад використання: Отримайте історію пошукової видачі для певних ключових фраз проєкту в конкретному регіоні, щоб аналізувати динаміку змін позицій у видачі та ефективність SEO-стратегії.
1. Використайте метод RtApiSerpResultsProcedure.getKeywordsSerpResultsHistory, щоб отримати
історію пошукової видачі за ключовими фразами проєкту в зазначеному регіоні.
2. Отримайте список позицій сайтів у пошуковій видачі, а також історію змін цих позицій у часі.
3. Використайте отримані дані для аналізу історії пошукової видачі: які сайти стабільно тримають високі
позиції, як змінюються позиції вашого домену у видачі. Визначте, які SEO-дії потрібно виконати для
покращення результатів.

Загальні параметри запиту та інструкція щодо використання Serpstat API

Доступні пошукові бази

Параметри запиту
Параметр	Опис	Тип	Обов'язковий	Значення за замовчуванням	Варіанти значень
id	Ідентифікатор запиту: відповідь буде містити цей же ідентифікатор	int/string	так		Будь-яке числове або текстове значення. Наприклад: 1, test, хаймарс
method	Назва методу API	string	так		RtApiSerpResultsProcedure.getKeywordsSerpResultsHistory
params	Об'єкт з параметрами {...}, в ньому перераховуються всі нижченаведені параметри та масиви [...]		так
projectId	Ідентифікатор проєкту	number	так		Числове значення ідентифікатору проєкту
projectRegionId	Ідентифiкатор регіону	number	так		Числове значення ідентифікатору регіону
page	Номер сторінки	number	так	1	Числове значення
pageSize	Кількість результатів на сторінку	number	ні	100	Числове значення. Можливі значення: 20, 50, 100, 200, 500
dateFrom	Дата початку періоду, за який потрібні дані	date	ні	Всі дати зняття позицій	Числове значення, формат даних: yyyy-mm-dd
dateTo	Дата кінця періоду, за яким потрібні дані	date	ні	Всі дати зняття позицій	Числове значення, формат даних: yyyy-mm-dd
sort	Сортування за параметрами	string	ні	alphabetically	"date" — Сортування за датою, "keyword" — Сортування за алфавітом
order	Напрям сортування	string	ні	desc	desc — за спаданням, asc — за зростанням
keywords	Ключові фрази, для яких потрібні сторінки та позиції	array	ні	Всі ключові фрази проєкту	Текстове значення. Максимальна кількість фраз, які можна фільтрувати — 1000.
withTags	Відображення тегів ключових фраз	string	ні	false	Текстове значення. "true" або "false"

Параметри відповіді
Параметр	Опис
id	Ідентифікатор відповіді: відповідає id в запиті
result	Містить в собі відповідь
data	Об'єкт з даними
projectId	Ідентифікатор проєкту
projectRegionId	Ідентифікатор регіону
keywords	Масив ключових фраз
keyword	Ключова фраза з даними
frequency	Частотність ключової фрази за місяць в обраній країні чи місті
expectedUrl	Цільова сторінка, яка оптимізується під конкретну фразу (якщо вона була додана у проєкті)
tags	Масив ідентифікаторів тегів та їх значення (назв тегів)
history	Масив дат з видачею по ключовій фразі
date	Дата видачі
positions	Масив позицій з доменом або сторінкою
position	Позиція
url	Сторінка, яка показується у результатах пошуку за певною фразою
summary info	Блок зведеної інформації
page	Поточна сторінка
page_total	Кількість сторінок з результатами при обраному параметрі pageSize
count	Кількість результатів на сторінку
total	Загальна кількість результатів
sort	Сортування за параметрами
order	Напрям сортування

Можливі помилки у відповіді
Код помилки	Опис
-32009\-32602	Невалідні параметри запиту. Опис які параметри та в чому проблема
-33054	Проєкт видалений
-34001	Невірний projectRegionId для проєкту
-34002	Діапазон дат повинен містити менше 30 дат аналізу
-34003	Ключові фрази не знайдено в проєкті
-32002	Порожній результат

За цим методом ліміти API не списуються.

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