v0.2.0-beta

OpenAPI 3.1.0

Створення завдань «Ad Traffic By Keywords»

Felo API Support

MIT

Сервер

https://openapi.felo.ai

Клієнтські бібліотеки

Shell Curl

DataForSEO

SEO, search-engine results, keyword research, backlinks and AI visibility data.

DataForSEO Операції

post/v1/beta/dataforseo/keywords_data/google_ads/ad_traffic_by_keywords/task_post

Створення завдань «Ad Traffic By Keywords»

Ставить у чергу прогноз кліків, показів і витрат для keywords за заданих bid і типу match та повертає id завдання. search_partners включає партнерську мережу Google. Відповідь обгорнуто в конверт DataForSEO: дані в tasks[0].result, результат у tasks[0].status_code — відхилений запит усе одно повертає HTTP 200. Це єдиний ендпоінт Google Ads тут без live-варіанта — прогнозування завжди йде через чергу. Отримуйте результат через get_dataforseo_keywords_gads_ad_traffic_fetch.

Довідкові ціни

Тарифікація: вартість відповіді за даними постачальника.
Довідкова оцінка запиту: USD 0.09.
Довідковий множник для клієнта: 1.0. Не застосовуйте його повторно до вже розрахованої суми клієнта.

Лише довідкові метадані, а не котирування для облікового запису, гарантована ціна чи ліміт витрат. Кредити ресурсів — це не кредити Felo. Остаточні списання здійснюються за записами білінгу Felo.

Тіло

application/json

Тип: array (object | null)[]
- bid
  Тип: number
  
  максимальна індивідуальна ставка
  обов'язкове поле
  зібрані дані ґрунтуватимуться на цьому значенні
  воно означає ціну, яку ви готові заплатити за оголошення; що вище значення ви вкажете тут, то вищі значення метрик отримаєте у відповіді
  докладніше — у цій статті довідкового центру
- date_from
  Тип: string
  
  початкова дата періоду прогнозування
  обов'язкове поле, якщо вказано 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_interval
  Тип: string | null
  
  інтервал дат прогнозування
  необов'язкове поле
  якщо вказати date_interval, date_from і date_to вказувати не потрібно
  можливі значення: next_week, next_month, next_quarter
  значення за замовчуванням: next_month
- date_to
  Тип: string
  
  кінцева дата періоду прогнозування
  обов'язкове поле, якщо вказано date_from
  якщо вказати date_from і date_to, date_interval вказувати не потрібно
  мінімальне значення — date_from +1 день
  максимальне значення — поточний день і місяць наступного року
  формат дати: "yyyy-mm-dd"
  приклад:
  "2022-10-30"
- keywords
  Тип: array string[]
  
  ключові слова
  обов'язкове поле
  максимальна кількість ключових слів: 1000
  максимальна кількість символів в одному ключовому слові: 80
  максимальна кількість слів в одній ключовій фразі: 10
  указані ключові слова приводяться до нижнього регістру
  Примітка #1: Google Ads може не повертати дані для певних груп ключових слів;
  Примітка #2: Google Ads надає об'єднані значення обсягу пошуку для груп схожих ключових слів
  щоб отримати обсяг пошуку для схожих ключових слів, рекомендуємо надсилати такі слова окремими запитами;
  Примітка #3: Google Ads не дозволяє використовувати певні символи й знаки (наприклад, UTF-символи, емодзі), тому їх не можна використовувати під час постановки завдання;
  щоб дізнатися, які символи й знаки можна використовувати, див. цю статтю
  
  Докладніше про правила та обмеження полів keyword і keywords в API DataForSEO читайте в статті Help Center
- language_code
  Тип: string | null
  
  код мови пошукової системи
  необов'язкове поле
  список доступних мов пошукової системи з їхніми language_code можна отримати окремим запитом до https://api.dataforseo.com/v3/keywords_data/google_ads/languages
  приклад:
  en
- language_name
  Тип: string | null
  
  повна назва мови пошукової системи
  необов'язкове поле
  список доступних мов пошукової системи з їхніми language_name можна отримати окремим запитом до https://api.dataforseo.com/v3/keywords_data/google_ads/languages
  приклад:
  English
- location_code
  Тип: integer | null
  
  код місцеположення пошукової системи
  необов'язкове поле
  якщо не вказати місцеположення, ви отримаєте результати по всьому світу, тобто для всіх доступних місцеположень;
  якщо використовуєте це поле, location_name або location_coordinate вказувати не потрібно;
  список доступних місцеположень пошукових систем з їхніми location_code можна отримати окремим запитом до https://api.dataforseo.com/v3/keywords_data/google_ads/locations
  приклад:
  2840
- location_coordinate
  Тип: string | null
  
  GPS-координати місцеположення
  необов'язкове поле
  якщо не вказати місцеположення, ви отримаєте результати по всьому світу, тобто для всіх доступних місцеположень;
  якщо використовуєте це поле, location_name або location_code вказувати не потрібно;
  параметр location_coordinate вказується у форматі "широта,довгота";
  дані буде надано для країни, до якої належать указані координати;
  приклад:
  52.6178549,-155.352142
- location_name
  Тип: string | null
  
  повна назва місцезнаходження пошукової системи
  необов'язкове поле
  якщо не вказати місцеположення, ви отримаєте результати по всьому світу, тобто для всіх доступних місцеположень;
  якщо використовуєте це поле, location_code або location_coordinate вказувати не потрібно
  список доступних місцезнаходжень пошукової системи з їхнім location_name можна отримати окремим запитом до https://api.dataforseo.com/v3/keywords_data/google_ads/locations
  приклад:
  London,England,United Kingdom
- match
  Тип: string
  
  тип відповідності ключових слів
  обов'язкове поле
  може приймати такі значення: exact, broad, phrase
- pingback_url
  Тип: string | null
  
  URL сповіщення про завершення завдання
  необов'язкове поле
  коли завдання буде виконано, ми надішлемо GET-запит на вказаний вами URL
  рядок «$id» можна використовувати як змінну $id, а «$tag» — як urlencoded-змінну $tag. Перед надсиланням запиту ми підставимо потрібні значення.
  приклад:
  http://your-server.com/pingscript?id=$id
  http://your-server.com/pingscript?id=$id&tag=$tag
  Примітка: спеціальні символи в pingback_url буде urlencoded;
  зокрема, символ # кодується як %23
  
  Докладніше див. в Help Center
- postback_url
  Тип: string | null
  
  URL для надсилання результатів завдання
  необов'язкове поле
  коли завдання буде виконано, ми надішлемо POST-запит з результатами, стиснутими у форматі gzip, на вказаний вами postback_url
  рядок «$id» можна використовувати як змінну $id, а «$tag» — як urlencoded-змінну $tag. Перед надсиланням запиту ми підставимо потрібні значення.
  приклад:
  http://your-server.com/postbackscript?id=$id
  http://your-server.com/postbackscript?id=$id&tag=$tag
  Примітка: спеціальні символи в postback_url буде urlencoded;
  зокрема, символ # кодується як %23
  
  Докладніше див. в Help Center
- sort_by
  Тип: string | null
  
  параметри сортування результатів
  необов'язкове поле
  використовуйте ці параметри для сортування результатів за relevance, average_cpc, cost або clicks за спаданням
  значення за замовчуванням: relevance
- tag
  Тип: string | null
  
  визначений користувачем ідентифікатор завдання
  необов'язкове поле
  обмеження — 255 символів
  цей параметр дає змогу ідентифікувати завдання й зіставити його з результатом
  вказане значення tag ви знайдете в об'єкті data відповіді

Відповіді

200
Тип: object | null · Response36Afe1097B20_KeywordsDataGoogleAdsAdTrafficByKeywordsTaskPostResponseInfo
cost
Тип: number | null Формат: double

загальна вартість завдань, USD

status_code
Тип: integer | null

загальний код стану. Повний список кодів відповіді можна знайти тут.

status_message
Тип: string | null

загальне інформаційне повідомлення. Повний список загальних інформаційних повідомлень можна знайти тут.

tasks
Тип: array (object | null)[] | null

масив завдань

Тип: object | null · Response36Afe1097B20_KeywordsDataGoogleAdsAdTrafficByKeywordsTaskPostTaskInfo
cost
Тип: number | null Формат: double

загальна вартість завдань, USD

data
Тип: object | null

містить ті самі параметри, які ви вказали в POST-запиті

propertyName
Тип: object | null
id
Тип: string | null

ідентифікатор завдання унікальний ідентифікатор завдання в нашій системі у форматі UUID

path
Тип: array (string | null)[] | null

шлях URL

result
Тип: object | null

масив результатів
у цьому випадку значення буде null

result_count
Тип: integer | null Формат: int64

кількість елементів у масиві result

status_code
Тип: integer | null

код стану завдання формується DataForSEO, може перебувати в діапазоні 10000-60000 Повний список кодів відповіді можна знайти тут.

status_message
Тип: string | null

інформаційне повідомлення завдання Повний список загальних інформаційних повідомлень можна знайти тут.

time
Тип: string | null

час виконання, секунди

tasks_count
Тип: integer | null Формат: int64

кількість завдань у масиві tasks

tasks_error
Тип: integer | null Формат: int64

кількість завдань у масиві tasks, повернутих з помилкою

time
Тип: string | null

загальний час виконання, секунди

version
Тип: string | null

поточна версія API
application/json
400

Не вдалося обробити запит. Перевірте параметри запиту.
401

Потрібен дійсний API-ключ Felo.
402

Запит неможливо виконати: умови білінгу не виконано.
403

Обліковий запис не має дозволу на цю операцію.
429

Досягнуто ліміту запитів або витрат.
502

Служба не змогла виконати запит.
503

API або служба білінгу тимчасово недоступні.
504

Час очікування обробки запиту вичерпано.
default

Відповідь із помилкою; наскрізні відповіді апстріму можуть використовувати формати постачальника

application/json

post/v1/beta/dataforseo/keywords_data/google_ads/ad_traffic_by_keywords/task_post

curl https://openapi.felo.ai/v1/beta/dataforseo/keywords_data/google_ads/ad_traffic_by_keywords/task_post \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '[
  {
    "language_code": "en",
    "location_code": 2840,
    "bid": 999,
    "match": "exact",
    "keywords": [
      "seo marketing"
    ]
  }
]'

Показати схему

{
  "version": null,
  "status_code": null,
  "status_message": null,
  "time": null,
  "cost": null,
  "tasks_count": null,
  "tasks_error": null,
  "tasks": [
    {
      "id": null,
      "status_code": null,
      "status_message": null,
      "time": null,
      "cost": null,
      "result_count": null,
      "path": [
        null
      ],
      "data": null,
      "result": null
    }
  ]
}

Успішна операція

Створення завдань «Ad Traffic By Keywords»

АвтентифікаціяRequired

DataForSEO

Створення завдань «Ad Traffic By Keywords»

Довідкові ціни