Подробнее о правилах и ограничениях полей keyword и keywords в API DataForSEO читайте в статье Help Center"
},
"bid": {
"type": "number",
"description": "максимальная индивидуальная ставка
обязательное поле
собираемые данные будут основаны на этом значении
оно обозначает цену, которую вы готовы заплатить за объявление; чем выше указанное здесь значение, тем выше значения возвращаемых метрик
подробнее — в этой статье справочного центра"
},
"match": {
"type": "string",
"description": "тип соответствия ключевых слов
обязательное поле
может принимать следующие значения: exact, broad, phrase"
},
"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"
},
"date_from": {
"type": "string",
"description": "начальная дата периода прогнозирования
обязательное поле, если указан date_to
если указать date_from и date_to, date_interval указывать не нужно
минимальное значение — завтрашняя дата
значение в date_from не должно быть позже date_to
формат даты: \"yyyy-mm-dd\"
пример:\"2021-10-30\" если эндпоинт Status возвращает false в поле actual_data, date_from можно установить на позапрошлый месяц и ранее;
если эндпоинт Status возвращает true в поле actual_data, date_from можно установить на прошлый месяц и ранее"
},
"date_to": {
"type": "string",
"description": "конечная дата периода прогнозирования
обязательное поле, если указан date_from
если указать date_from и date_to, date_interval указывать не нужно
минимальное значение — date_from +1 день
максимальное значение — текущий день и месяц следующего года
формат даты: \"yyyy-mm-dd\"
пример:\"2022-10-30\""
},
"date_interval": {
"type": [
"string",
"null"
],
"description": "интервал дат прогнозирования
необязательное поле
если указать date_interval, date_from и date_to указывать не нужно
возможные значения: next_week, next_month, next_quarter
значение по умолчанию: next_month"
},
"sort_by": {
"type": [
"string",
"null"
],
"description": "параметры сортировки результатов
необязательное поле
используйте эти параметры для сортировки результатов по relevance, average_cpc, cost или clicks по убыванию
значение по умолчанию: relevance"
},
"postback_url": {
"type": [
"string",
"null"
],
"description": "URL для отправки результатов задачи
необязательное поле
когда задача будет выполнена, мы отправим POST-запрос с результатами, сжатыми в формате gzip, на указанный вами postback_url
строку «$id» можно использовать как переменную $id, а «$tag» — как urlencoded-переменную $tag. Перед отправкой запроса мы подставим нужные значения.
пример:http://your-server.com/postbackscript?id=$idhttp://your-server.com/postbackscript?id=$id&tag=$tag
Примечание: специальные символы в postback_url будут urlencoded;
в частности, символ # кодируется как %23
Подробнее см. в Help Center"
},
"pingback_url": {
"type": [
"string",
"null"
],
"description": "URL уведомления о завершении задачи
необязательное поле
когда задача будет выполнена, мы отправим GET-запрос на указанный вами URL
строку «$id» можно использовать как переменную $id, а «$tag» — как urlencoded-переменную $tag. Перед отправкой запроса мы подставим нужные значения.
пример:http://your-server.com/pingscript?id=$idhttp://your-server.com/pingscript?id=$id&tag=$tag
Примечание: специальные символы в pingback_url будут urlencoded;
в частности, символ # кодируется как %23
Подробнее см. в Help Center"
},
"tag": {
"type": [
"string",
"null"
],
"description": "пользовательский идентификатор задачи
необязательное поле
ограничение — 255 символов
этот параметр позволяет идентифицировать задачу и сопоставить её с результатом
указанное значение tag вы найдёте в объекте data ответа"
}
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"bid": 999,
"match": "exact",
"keywords": [
"seo marketing"
]
}
]
}
]
},
"example": [
{
"language_code": "en",
"location_code": 2840,
"bid": 999,
"match": "exact",
"keywords": [
"seo marketing"
]
}
]
}
```
## Responses
### 200 — Успешная операция
Headers:
- `X-Request-Id` (string) — Идентификатор запроса, который нужно указать при обращении в поддержку Felo.
**application/json**
Schema: object | null
```json
{
"type": [
"object",
"null"
],
"oneOf": [
{
"$ref": "#/components/schemas/Response36Afe1097B20_KeywordsDataGoogleAdsAdTrafficByKeywordsTaskPostResponseInfo"
}
]
}
```
### 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_KeywordsDataGoogleAdsAdTrafficByKeywordsTaskPostResponseInfo
`#/components/schemas/Response36Afe1097B20_KeywordsDataGoogleAdsAdTrafficByKeywordsTaskPostResponseInfo`
```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_KeywordsDataGoogleAdsAdTrafficByKeywordsTaskPostTaskInfo"
}
]
},
"description": "массив задач"
}
}
}
]
}
```
### Response36Afe1097B20_KeywordsDataGoogleAdsAdTrafficByKeywordsTaskPostTaskInfo
`#/components/schemas/Response36Afe1097B20_KeywordsDataGoogleAdsAdTrafficByKeywordsTaskPostTaskInfo`
```json
{
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Response36Afe1097B20_BaseResponseTaskInfo"
},
{
"type": "object",
"properties": {
"result": {
"type": [
"object",
"null"
],
"description": "массив результатов
в этом случае значение будет null"
}
}
}
]
}
```