Отримання списку топ-20 доменів за фразами проекту

Метод RtApiSerpResultsProcedure.getTopCompetitorsDomainsHistory повертає список доменів, що потрапили у топ-20 пошукової видачi у регіонi мінімум за двома фразами проєкту. Аналогічний до звіту Моніторинг позицій — Конкуренти.

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

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

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

Параметри запиту
Параметр	Опис	Тип	Обов'язковий	Значення за замовчуванням	Варіанти значень
id	Ідентифікатор запиту: відповідь буде містити цей же ідентифікатор	int/string	ні		Будь-яке числове або текстове значення. Наприклад: 1, test, хаймарс
method	Назва методу API	string	ні		RtApiSerpResultsProcedure.getTopCompetitorsDomainsHistory
params	Об'єкт з параметрами {...}, в ньому перераховуються всі нижченаведені параметри та масиви [...]		ні
projectId	Ідентифікатор проєкту	number	ні		Числове значення ідентифікатору проєкту
projectRegionId	Ідентифiкатор регіону	number	ні		Числове значення ідентифікатору регіону
page	Номер сторінки	number	ні	1	Числове значення
pageSize	Кількість результатів на сторінку	number	так	100	Числове значення. Можливі значення: 20, 50, 100, 200, 500
dateFrom	Дата початку періоду, за який потрібні дані	date	так	30 днів від останнього зняття позицій	Числове значення, формат даних: yyyy-mm-dd
dateTo	Дата кінця періоду, за яким потрібні дані	date	так	Дата останнього зняття позицій	Числове значення, формат даних: yyyy-mm-dd
sort	Сортування за параметрами	string	так	traffic	Можливі значення: "sum_traffic" — за розподіленням трафіку, "keywords_count" — за кількістю ключових фраз, "avg_position" — за середньою позицією, "position_ranges" — за топами розподілення позицій, "ads_count" — за кількістю платних оголошень
sortRange	Використовується при сортуванні за position_ranges	string	так		Можливі значення: "top1\top2"... — розподілення за позиціями, "keywords_count_bottom\keywords_count_top" — розподілення за рекламними блоками, "avg_position_top\avg_position_bottom" — середня позиція за рекламними блоками
order	Напрям сортування	string	так	desc	desc — за спаданням, asc — за зростанням
domain	Домен/домени, за якими потрібні дані	array	так	Всі домени, що потрапили у топ-20 хоча б по 2 фразах проєкту	Текстове значення. Формат даних: ["domain1.com", "domain2.com"]

Параметри відповіді
Параметр	Опис
id	Ідентифікатор відповіді: відповідає id в запиті
result	Містить в собі відповідь
data	Об'єкт з даними
projectId	Ідентифікатор проєкту
projectRegionId	Ідентифікатор регіону
competitors	Масив з доменами
domain	Домен, що потрапив у топ-20 хоча б за двома фразами проєкту
dates	Масив дат з даними за вказаним доменом
date	Дата, за якою виводяться дані по домену
value	Значення параметру
traffic_distribution	Розподіл трафіку домену серед усіх доменів топ-20 пошукової видачі
avg_position	Середня позиція домену серед кращих позицій по ключових фразах проєкту
keywords_count	Кількість ключових фраз, за якими домен потрапив у видачу
keywords_by_ranges	Розподіл ключових фраз за діапазонами позицій домену
top1	Ключові фрази, за якими домен зайняв 1 позицію
top3	Ключові фрази, за якими домен зайняв 2-3 позиції
top5	Ключові фрази, за якими домен зайняв 4-5 позиції
top10	Ключові фрази, за якими домен зайняв 6-10 позиції
top20	Ключові фрази, за якими домен зайняв 11-20 позиції
top101	Ключові фрази, за якими домен зайняв 21-100 позиції в Google
	Регіони з контекстом
ads_count	Кількість оголошень домену, які були виявлені в контексті
keywords_count_blocks	Розподіл ключових фраз у блоках контексту
avg_position_blocks	Середня позиція у блоках контексту
top	Верхній блок реклами
sidebar	Бічний блок реклами
bottom	Нижній блок реклами
summary info	Блок зведеної інформації
page	Поточна сторінка
page_total	Кількість сторінок з результатами при обраному параметрі pageSize
count	Кількість результатів на сторінку
total	Загальна кількість результатів
sort	Сортування за параметрами
order	Напрям сортування

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

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

Example

Request data:

{
    "id": "1",
    "method": "RtApiSerpResultsProcedure.getTopCompetitorsDomainsHistory",
   "params": {
        "projectId": 853932,
        "projectRegionId": 293402,
        "page": 1,
        "pageSize": 20,
        "dateFrom": "2021-07-26",
        "dateTo": "2021-07-27",
        "sort": "domain",
        "order": "asc",
        "domains": [
            "adidas.com",
            "nike.com"
        ]  
    }
}

Response data:

{
    "id": "1",
    "result": {
        "data": {
            "projectId": 853932,
            "projectRegionId": 293402,
            "competitors": [
                {
                    "domain": "adidas.com",
                    "dates": [
                        {
                            "date": "2021-07-26",
                            "result": {
                                "traffic_distribution": {
                                    "value": 19.390000000000001
                                },
                                "avg_position": {
                                    "value": 2.7000000000000002
                                },
                                "keywords_count": {
                                    "value": 12
                                },
                                "keywords_by_ranges": {
                                    "top1": {
                                        "value": 5
                                    },
                                    "top3": {
                                        "value": 3
                                    },
                                    "top5": {
                                        "value": 3
                                    },
                                    "top10": {
                                        "value": 1
                                    },
                                    "top20": {
                                        "value": 0
                                    },
                                    "top101": {
                                        "value": 0
                                    }
                                }
                            }
                        },
                        {
                            "date": "2021-07-27",
                            "result": {
                                "traffic_distribution": {
                                    "value": 17.25
                                },
                                "avg_position": {
                                    "value": 3.1000000000000001
                                },
                                "keywords_count": {
                                    "value": 12
                                },
                                "keywords_by_ranges": {
                                    "top1": {
                                        "value": 6
                                    },
                                    "top3": {
                                        "value": 2
                                    },
                                    "top5": {
                                        "value": 2
                                    },
                                    "top10": {
                                        "value": 2
                                    },
                                    "top20": {
                                        "value": 0
                                    },
                                    "top101": {
                                        "value": 0
                                    }
                                }
                            }
                        }
                    ]
                },
                {
                    "domain": "nike.com",
                    "dates": [
                        {
                            "date": "2021-07-26",
                            "result": {
                                "traffic_distribution": {
                                    "value": 7.6299999999999999
                                },
                                "avg_position": {
                                    "value": 15.1
                                },
                                "keywords_count": {
                                    "value": 9
                                },
                                "keywords_by_ranges": {
                                    "top1": {
                                        "value": 0
                                    },
                                    "top3": {
                                        "value": 2
                                    },
                                    "top5": {
                                        "value": 1
                                    },
                                    "top10": {
                                        "value": 3
                                    },
                                    "top20": {
                                        "value": 2
                                    },
                                    "top101": {
                                        "value": 1
                                    }
                                }
                            }
                        },
                        {
                            "date": "2021-07-27",
                            "result": {
                                "traffic_distribution": {
                                    "value": 7.6799999999999997
                                },
                                "avg_position": {
                                    "value": 14.6
                                },
                                "keywords_count": {
                                    "value": 9
                                },
                                "keywords_by_ranges": {
                                    "top1": {
                                        "value": 0
                                    },
                                    "top3": {
                                        "value": 2
                                    },
                                    "top5": {
                                        "value": 1
                                    },
                                    "top10": {
                                        "value": 3
                                    },
                                    "top20": {
                                        "value": 2
                                    },
                                    "top101": {
                                        "value": 1
                                    }
                                }
                            }
                        }
                    ]
                }
            ]
        },
        "summary_info": {
            "page": 1,
            "page_total": 1,
            "count": 20,
            "total": 2,
            "sort": "domain",
            "order": "asc"
        },
        "spent_limits": 0
    }
}