Подробнее о правилах и ограничениях полей keyword и keywords в API DataForSEO читайте в статье Help Center"
},
"location_name": {
"type": [
"string",
"null"
],
"description": "полное название местоположения поисковой системы
необязательное поле
если не указать местоположение, вы получите результаты по всему миру, то есть по всем доступным местоположениям;
если используете это поле, location_code или location_coordinate указывать не нужно
список доступных местоположений поисковой системы с их location_name можно получить отдельным запросом к https://api.dataforseo.com/v3/keywords_data/google_ads/locations
пример:London,England,United Kingdom"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "код местоположения поисковой системы
необязательное поле
если не указать местоположение, вы получите результаты по всему миру, то есть по всем доступным местоположениям;
если используете это поле, location_name или location_coordinate указывать не нужно;
список доступных местоположений поисковых систем с их location_code можно получить отдельным запросом к https://api.dataforseo.com/v3/keywords_data/google_ads/locations
пример:2840"
},
"location_coordinate": {
"type": [
"string",
"null"
],
"description": "GPS-координаты местоположения
необязательное поле
если не указать местоположение, вы получите результаты по всему миру, то есть по всем доступным местоположениям;
если используете это поле, location_name или location_code указывать не нужно;
параметр location_coordinate указывается в формате \"широта,долгота\";
данные будут предоставлены для страны, к которой относятся указанные координаты;
пример:52.6178549,-155.352142"
},
"language_name": {
"type": [
"string",
"null"
],
"description": "полное название языка поисковой системы
необязательное поле
список доступных языков поисковой системы с их language_name можно получить отдельным запросом к https://api.dataforseo.com/v3/keywords_data/google_ads/languages
пример:English"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "код языка поисковой системы
необязательное поле
список доступных языков поисковой системы с их language_code можно получить отдельным запросом к https://api.dataforseo.com/v3/keywords_data/google_ads/languages
пример:en"
},
"search_partners": {
"type": [
"boolean",
"null"
],
"description": "включить партнёров Google Поиска
необязательное поле
если указать true, результаты будут предоставлены для собственных, управляемых и синдицированных сетей Google и партнёрских сайтов, размещающих поиск Google;
значение по умолчанию: false — результаты возвращаются для сайтов поиска Google"
},
"date_from": {
"type": [
"string",
"null"
],
"description": "начальная дата временного диапазона
необязательное поле
формат даты: \"yyyy-mm-dd\"
минимальное значение: 4 года от текущей даты
по умолчанию данные возвращаются за последние 12 месяцев;
Примечание: указанная дата не может быть больше даты, указанной в date_to, и/или вчерашней даты; если эндпоинт Status возвращает false в поле actual_data, date_from можно установить на позапрошлый месяц и ранее;
если эндпоинт Status возвращает true в поле actual_data, date_from можно установить на прошлый месяц и ранее"
},
"date_to": {
"type": [
"string",
"null"
],
"description": "конечная дата временного диапазона
необязательное поле
Примечание: указанная дата не может быть больше прошлого месяца; Google Ads не возвращает данные за текущий месяц;
если не указать это поле, по умолчанию будет использована вчерашняя дата
формат даты: \"yyyy-mm-dd\"
пример:\"2022-11-30\""
},
"include_adult_keywords": {
"type": [
"boolean",
"null"
],
"description": "включить ключевые слова, связанные со взрослым контентом
необязательное поле
если установлено true, в ответ будут включены ключевые слова для взрослых
значение по умолчанию: false
примечание: API может не возвращать данные по таким ключевым словам из-за ограничений Google Ads"
},
"sort_by": {
"type": [
"string",
"null"
],
"description": "параметры сортировки результатов
необязательное поле
используйте эти параметры для сортировки результатов по relevance, search_volume, competition_index, low_top_of_page_bid или high_top_of_page_bid по убыванию
значение по умолчанию: relevance"
},
"tag": {
"type": [
"string",
"null"
],
"description": "пользовательский идентификатор задачи
необязательное поле
ограничение — 255 символов
этот параметр позволяет идентифицировать задачу и сопоставить её с результатом
указанное значение tag вы найдёте в массиве data ответа"
}
},
"example": [
{
"location_code": 2840,
"keywords": [
"buy laptop",
"cheap laptops for sale",
"purchase laptop"
],
"date_from": "2021-08-01",
"search_partners": true
}
]
}
]
},
"example": [
{
"location_code": 2840,
"keywords": [
"buy laptop",
"cheap laptops for sale",
"purchase laptop"
],
"date_from": "2021-08-01",
"search_partners": true
}
]
}
```
## Responses
### 200 — Успешная операция
Headers:
- `X-Request-Id` (string) — Идентификатор запроса, который нужно указать при обращении в поддержку Felo.
**application/json**
Schema: object | null
```json
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response36Afe1097B20_KeywordsDataGoogleAdsSearchVolumeLiveResponseInfo"
}
]
}
```
### 400 — Запрос не удалось обработать. Проверьте параметры запроса.
### 401 — Требуется действительный API-ключ Felo.
### 402 — Запрос не может быть выполнен: не выполнено требование биллинга.
### 403 — Аккаунту не разрешено выполнять эту операцию.
### 429 — Достигнут лимит запросов или расходов.
### 502 — Сервис не смог выполнить запрос.
### 503 — API или сервис биллинга временно недоступны.
### 504 — Истекло время ожидания обработки запроса.
### default — Ответ с ошибкой; сквозные ответы upstream могут использовать форматы провайдера
**application/json**
Schema:
```json
{}
```
## Schema definitions
### Response36Afe1097B20_BaseResponseInfo
`#/components/schemas/Response36Afe1097B20_BaseResponseInfo`
```json
{
"properties": {
"version": {
"type": [
"string",
"null"
],
"description": "текущая версия API"
},
"status_code": {
"type": [
"integer",
"null"
],
"description": "общий код состояния.\nПолный список кодов ответа можно найти здесь."
},
"status_message": {
"type": [
"string",
"null"
],
"description": "общее информационное сообщение.\nПолный список общих информационных сообщений можно найти здесь."
},
"time": {
"type": [
"string",
"null"
],
"description": "общее время выполнения, секунды"
},
"cost": {
"type": [
"number",
"null"
],
"description": "общая стоимость задач, USD",
"format": "double"
},
"tasks_count": {
"type": [
"integer",
"null"
],
"description": "число задач в массиве tasks",
"format": "int64"
},
"tasks_error": {
"type": [
"integer",
"null"
],
"description": "число задач в массиве tasks, возвращённых с ошибкой",
"format": "int64"
}
}
}
```
### Response36Afe1097B20_BaseResponseTaskInfo
`#/components/schemas/Response36Afe1097B20_BaseResponseTaskInfo`
```json
{
"properties": {
"id": {
"type": [
"string",
"null"
],
"description": "идентификатор задачи\nуникальный идентификатор задачи в нашей системе в формате UUID"
},
"status_code": {
"type": [
"integer",
"null"
],
"description": "код состояния задачи\nформируется DataForSEO, может находиться в диапазоне 10000-60000\nПолный список кодов ответа можно найти здесь."
},
"status_message": {
"type": [
"string",
"null"
],
"description": "информационное сообщение задачи\nПолный список общих информационных сообщений можно найти здесь."
},
"time": {
"type": [
"string",
"null"
],
"description": "время выполнения, секунды"
},
"cost": {
"type": [
"number",
"null"
],
"description": "общая стоимость задач, USD",
"format": "double"
},
"result_count": {
"type": [
"integer",
"null"
],
"description": "число элементов в массиве result",
"format": "int64"
},
"path": {
"type": [
"array",
"null"
],
"items": {
"type": [
"string",
"null"
]
},
"description": "путь URL"
},
"data": {
"type": [
"object",
"null"
],
"additionalProperties": {
"type": [
"object",
"null"
]
},
"description": "содержит те же параметры, что вы указали в POST-запросе"
}
}
}
```
### Response36Afe1097B20_KeywordsDataGoogleAdsSearchVolumeLiveResponseInfo
`#/components/schemas/Response36Afe1097B20_KeywordsDataGoogleAdsSearchVolumeLiveResponseInfo`
```json
{
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response36Afe1097B20_BaseResponseInfo"
},
{
"type": "object",
"properties": {
"tasks": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response36Afe1097B20_KeywordsDataGoogleAdsSearchVolumeLiveTaskInfo"
}
]
},
"description": "массив задач"
}
}
}
]
}
```
### Response36Afe1097B20_KeywordsDataGoogleAdsSearchVolumeLiveResultInfo
`#/components/schemas/Response36Afe1097B20_KeywordsDataGoogleAdsSearchVolumeLiveResultInfo`
```json
{
"type": "object",
"properties": {
"keyword": {
"type": [
"string",
"null"
],
"description": "ключевое слово
ключевое слово возвращается с декодированным %## (символ плюса '+' декодируется в пробел)"
},
"spell": {
"type": [
"string",
"null"
],
"description": "правильное написание ключевого слова
Примечание:если ключевое слово в массиве POST выглядит с ошибкой, данные будут возвращены для ключевого слова с правильным написанием;
для проверки и валидации написания ключевых слов мы используем функциональность Google Ads API, подробнее по этой ссылке"
},
"location_code": {
"type": [
"integer",
"null"
],
"description": "код местоположения в массиве POST
если данных нет, значение — null"
},
"language_code": {
"type": [
"string",
"null"
],
"description": "код языка в массиве POST
если данных нет, значение — null"
},
"search_partners": {
"type": [
"boolean",
"null"
],
"description": "указывает, включены ли в ответ данные партнёрских сетей"
},
"competition": {
"type": [
"string",
"null"
],
"description": "конкуренция
относительный уровень конкуренции по указанному ключевому слову только в платной выдаче SERP;
значение основано на данных Google Ads и может принимать следующие значения: HIGH, MEDIUM, LOW;
если данных нет, значение — null;
подробнее о метрике — в этой статье справочного центра"
},
"competition_index": {
"type": [
"integer",
"null"
],
"description": "конкуренция
относительный уровень конкуренции по указанному ключевому слову только в платной выдаче SERP;
значение основано на данных Google Ads и может находиться в диапазоне от 0 до 100 включительно;
если данных нет, значение — null;
подробнее о метрике — в этой статье справочного центра"
},
"search_volume": {
"type": [
"integer",
"null"
],
"description": "среднемесячный показатель поискового объёма;
приблизительное количество поисковых запросов по указанной идее ключевого слова на google.com или google.com и партнёрских сайтах с учётом таргетинга пользователя;
если данных нет, значение —_nulln",
"format": "int64"
},
"low_top_of_page_bid": {
"type": [
"number",
"null"
],
"description": "минимальная ставка для показа объявления в верхней части первой страницы
обозначает значение, превышающее примерно 20% минимальных ставок, при которых показывались объявления (на основе статистики Google Ads для рекламодателей);
значение может различаться в зависимости от локации, указанной в POST-запросе"
},
"high_top_of_page_bid": {
"type": [
"number",
"null"
],
"description": "максимальная ставка для показа объявления в верхней части первой страницы
обозначает значение, превышающее примерно 80% минимальных ставок, при которых показывались объявления (на основе статистики Google Ads для рекламодателей);
значение может различаться в зависимости от локации, указанной в POST-запросе"
},
"cpc": {
"type": [
"number",
"null"
],
"description": "цена за клик
сумма (USD), уплачиваемая за каждый клик по объявлению, показанному для данного ключевого слова"
},
"monthly_searches": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response36Afe1097B20_MonthlySearchesInfo"
}
]
},
"description": "поисковых запросов в месяц
приблизительное количество поисковых запросов по этой идее ключевого слова (по умолчанию за последние двенадцать месяцев), нацеленных на указанные географические локации;
если данных нет, значение —_nulln"
}
}
}
```
### Response36Afe1097B20_KeywordsDataGoogleAdsSearchVolumeLiveTaskInfo
`#/components/schemas/Response36Afe1097B20_KeywordsDataGoogleAdsSearchVolumeLiveTaskInfo`
```json
{
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response36Afe1097B20_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"array",
"null"
],
"items": {
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response36Afe1097B20_KeywordsDataGoogleAdsSearchVolumeLiveResultInfo"
}
]
},
"description": "массив результатов"
}
}
}
]
}
```
### Response36Afe1097B20_MonthlySearchesInfo
`#/components/schemas/Response36Afe1097B20_MonthlySearchesInfo`
```json
{
"type": "object",
"properties": {
"year": {
"type": [
"integer",
"null"
],
"description": "год"
},
"month": {
"type": [
"integer",
"null"
],
"description": "месяц"
},
"search_volume": {
"type": [
"integer",
"null"
],
"description": "среднемесячный показатель поискового объёма"
}
}
}
```