Рекламні оголошення за ключовою фразою V4 (SerpstatKeywordProcedure.getAdKeywords)

Метод SerpstatKeywordProcedure.getAdKeywords виконує пошук ключових слів в платній видачі та рекламних оголошень по ключовому слову. Аналогічний до звіту Аналіз ключових слів — РРС-аналіз — Ключові слова.

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

Параметри запиту
Параметр	Опис	Тип	Опціональність	Значення за замовчуванням	Варіанти значень
id	Ідентифікатор запиту: відповідь буде містити цей же ідентифікатор. Допускається введення будь-якого числового (number) або текстового (string) значення	int/string	ні		1, test
method	Назва методу API	string	ні		SerpstatKeywordProcedure.getAdKeywords
params	Об'єкт з параметрами {...}, в ньому перераховуються всі нижченаведені параметри та масиви [...]	array	ні
keyword	Фраза, для якої буде відбуватися пошук	string	ні		iphone
se	Ідентифікатор пошукової бази, по якій буде проходити пошук	string	ні		g_us
domains	Список доменів	array	так	[]	["apple.com","verizon.com"]
minusKeywords	Масив мінус-слів при пошуку	array	так	[]	["app", "apple"]
filters	Умови фільтрації	json object	так		{"queries_from": 10} {"queries_to": 10}
sort	Порядок сортування результатів в форматі: {{{Field}}: {{order}}} field — поле, за яким потрібно виконати сортування: * keyword_length * position * type * cost * concurrency * found_results * region_queries_count * region_queries_count_wide order — напрямок сортування (asc — за зростанням, desc — за спаданням)	json object	так	{"position": "asc", "region_queries_count":"desc"}	{"cost": "asc"}
page	Номер сторінки у відповіді	int	так	1	"page": "5"
size	Кількість результатів на сторінку у відповіді	int	так	100	"size": "10" min: 1, max: 1000

Для фільтрації результатів використовуйте наступні параметри:

Параметр	Опис	Можливі значення
position_from	Мінімальна позиція ключового слова	1-100
position_to	Максимальна позиція ключового слова	1-100
queries_from	Мінімальна кількість запитів на місяць	0-100000000
queries_to	Максимальна кількість запитів на місяць	0-100000000
cost_from	Мінімальна вартість за клік	0-200
cost_to	Максимальна вартість за клік	0-200
concurrency_from	Мінімальне значення конкуренції	0-100
concurrency_to	Максимальне значення конкуренції	0-100
results_from	Мінімальне значення результатів	0-100000000
results_to	Максимальне значення результатів	0-100000000
length_from	Мінімальне значення довжини фрази	0-100000000
length_to	Максимальне значення довжини фрази	0-100000000

Параметри відповіді
Параметр	Опис
id	Ідентифікатор відповіді: відповідає id в запиті
result	Містить в собі відповідь
data	Масив з даними
keyword	Ключова фраза, за якою відображається оголошення
keyword_length	Кількість слів, розділених пробілом в ключовій фразі
domain	Домен
subdomain	Піддомен сайту, який відображається в пошуковій видачі
url	URL оголошення, який відображається в пошуковій видачі за даним запитом
title	Заголовок оголошення
text	Текст оголошення
position	Позиції оголошень контекстній рекламі
type	Місце знаходження оголошення в SERP (1 - над; 2 - під; 3 - справа)
cost	Ціна за клік, $
concurrency	Конкурентність в контекстній рекламі (0-100%)
found_results	Кількість знаденних результатів за ключовою фразою
region_queries_count	Частотність ключової фрази у вибраному регіоні
region_queries_count_wide	Частотність ключової фрази у широкій відповідності
types	Перелік додаткових запитів, які відображаються в SERP (наприклад, відео, карусель зображень, карта та інше)
geo_names	Список топонімів в масиві, якщо топонім присутній у ключовій фразі. Якщо ні — масив пустий
difficulty	Оцінка рівня конкуренції за ключовою фразою для просування в топ-10 (від 0 до 100%)
summary_info	Об'єкт з даними відповіді
page	Номер сторінки
total	Кількість знайдених ключових фраз в РРС за шуканою фразою
left_lines	Кількість API-рядків, що залишилися

Ліміти: кількість списаних лімітів відповідає кількості отриманих ключових фраз у відповіді. Частина відповіді API, за яку знімається 1 ліміт:

{
    "keyword": "upgrade iphone x to xs",
    "keyword_length": 5,
    "domain": "apple.com",
    "subdomain": "www.apple.com",
    "url": "https://www.apple.com/iphone/",
    "title": "Trade in for iPhone 12 - Apple Official Site",
    "text": "Get $90 - $515 off iPhone 12 when you trade in an iPhone 7 or newer. Terms apply. A14 Bionic Chip. 5G speed. Ceramic Shield. Super Retina XDR display. Services: Free no-contact delivery, Finance with Apple Card, 3% cash back w/Apple Card, Prepaid mail-in kit.",
    "position": 2,
    "type": "1",
    "cost": 0,
    "concurrency": 50,
    "found_results": 325000000,
    "region_queries_count": 10,
    "region_queries_count_wide": 0,
    "types": [
        "carousel",
        "also_asks",
        "video",
        "ads_top"
        ],
    "geo_names": [],
    "difficulty": null
},

Example

Request data:

{
 "id": "1",
 "method": "SerpstatKeywordProcedure.getAdKeywords",
 "params": {
   "keyword": "iphone",
   "se": "g_us",
   "domains": ["apple.com","verizon.com"],
   "filters": {"position_from": "2", "position_to":"3"},
   "sort" : {"region_queries_count":"asc"},
   "page": "1",
   "size": "10"
    }
}

Response data:

{
    "id": "1",
    "result": {
        "data": [
            {
                "keyword": "upgrade iphone x to xs",
                "keyword_length": 5,
                "domain": "apple.com",
                "subdomain": "www.apple.com",
                "url": "https://www.apple.com/iphone/",
                "title": "Trade in for iPhone 12 - Apple Official Site",
                "text": "Get $90 - $515 off iPhone 12 when you trade in an iPhone 7 or newer. Terms apply. A14 Bionic Chip. 5G speed. Ceramic Shield. Super Retina XDR display. Services: Free no-contact delivery, Finance with Apple Card, 3% cash back w/Apple Card, Prepaid mail-in kit.",
                "position": 2,
                "type": "1",
                "cost": 0,
                "concurrency": 50,
                "found_results": 325000000,
                "region_queries_count": 10,
                "region_queries_count_wide": 0,
                "types": [
                    "carousel",
                    "also_asks",
                    "video",
                    "ads_top"
                ],
                "geo_names": [],
                "difficulty": null
            },
            {
                "keyword": "iphone 7128gb price",
                "keyword_length": 3,
                "domain": "apple.com",
                "subdomain": "www.apple.com",
                "url": "https://www.apple.com/iphone/",
                "title": "iPhone - Apple Official Site",
                "text": "Blast past fast. iPhone 12 now in purple. Pre-order on 4.23. Save up to $320 on iPhone 12 after trade-in with T-Mobile. Terms apply. Water resistant. Retina display. Wide camera. Privacy built in. Services: Online personal session, Chat for shopping help.",
                "position": 2,
                "type": "3",
                "cost": 0,
                "concurrency": 0,
                "found_results": 1170000,
                "region_queries_count": 10,
                "region_queries_count_wide": 0,
                "types": [
                    "a_box_fsnippet",
                    "kn_graph_brand",
                    "also_asks",
                    "shopping_top",
                    "ads_bot"
                ],
                "geo_names": [],
                "difficulty": null
            }
        ],
        "summary_info": {
            "page": 1,
            "total": 178,
            "left_lines": 998625
        }
    }
}