Відповіді ШІ

API + MCP

POST/v3/brand-radar/ai-responses

Запити до цього ендпойнта споживають одиниці API залежно від параметра prompts: запити, що повертають лише дані користувацького запиту, безплатні, а запити, що включають дані запитів Ahrefs, оплачуються за тарифом Standard на одиниці API.

Тіло запиту

selectarray<string>Required

Список полів, які потрібно повернути.

Example:["field_a","field_b"]

whereobject

Вираз фільтра. Розпізнаються такі ідентифікатори стовпців (вони відрізняються від ідентифікаторів, які розпізнає параметр select).

report_idstring

ID звіту, який потрібно використати. Якщо його вказано, інші параметри беруться зі звіту (бренд, конкуренти, ринок, країна, фільтри). Якщо вказано країну або фільтри, вони замінюють ті, що у звіті. Його можна знайти в URL вашого звіту Brand Radar в Ahrefs: https://app.ahrefs.com/brand-radar/reports/#report_id#/...

brandsarray<object>

Список назв і вебсайтів брендів для пошуку.

Default:[]

At least one of names or url_groups is required

namesarray<string>

Назви бренду/конкурента

Example:["ahrefs","ahrefs seo"]

url_groupsarray<object>

targetstring (domain)required

Домен цілі

Example:ahrefs.com

scopestringrequired

Область дії цілі.

Дозволені значення:urlpathdomainsubdomains

competitorsarray<object>

Список назв і вебсайтів конкурентів для пошуку.

Default:[]

At least one of names or url_groups is required

namesarray<string>

Назви бренду/конкурента

Example:["ahrefs","ahrefs seo"]

url_groupsarray<object>

targetstring (domain)required

Домен цілі

Example:ahrefs.com

scopestringrequired

Область дії цілі.

Дозволені значення:urlpathdomainsubdomains

content_filterobject

Необов’язкові фрази, які використовуються для включення або виключення результатів залежно від їхнього вмісту.

includearray<string>

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

excludearray<string>

Приховувати результати, що містять будь-яку з цих точних фраз.

data_sourcearray<string>Required

Список моделей чатботів. Усі моделі можна поєднувати між собою. Модуль claude підтримує лише користувацькі запити.
Моделі google_ai_overviews_keywords і google_ai_mode_keywords надають дані про видимість в Оглядах від ШІ / режимі ШІ, визначену на основі пошукових запитів Google (ключових слів), а не запитів до моделей.

Дозволені значення:chatgptgoogle_ai_overviewsgoogle_ai_modegeminiperplexitycopilotclaudegrokgoogle_ai_overviews_keywordsgoogle_ai_mode_keywords

countryarray<string>

Список дволітерних кодів країн (ISO 3166-1 alpha-2).

Дозволені значення:adaeafagaialamaoarasatauawazba…

Default:[]

promptsstring

Тип запитів, які слід використовувати. Якщо не вказано, використовуватимуться обидва. Для користувацьких запитів потрібно вказати report_id.

Дозволені значення:ahrefscustom

limitinteger

Кількість результатів, які потрібно повернути.

Default:1000

datestring (date)

Дата для пошуку у форматі YYYY-MM-DD.

date_comparedstring (date)

Дата для порівняння з date у форматі YYYY-MM-DD. Має бути строго ранішою за date. Якщо задано, звіт охоплює кожен запит, на який було надано відповідь у будь-яку з цих дат, а поле status показує, як кожен із них змінився між ними. Запит, на який було надано відповідь лише в date_compared, позначається як lost, а решта його полів описують відповідь для date_compared, оскільки для date її немає.

order_by

Як упорядкувати результати: за стовпцем або за тим, як у відповідях ідеться про один бренд, як це робить сторінка «Настрої» в Brand Radar.

Стовпець, за яким потрібно впорядкувати результати.

Дозволені значення:relevancevolume

tags_filterobject

Вираз фільтрації для тегів запитів. Потрібен report_id. Використовує синтаксис фільтрів з такими обмеженнями: єдина допустима назва поля — "tag"; допустимі лише такі оператори: "eq", "neq", "substring", "isubstring", "phrase_match", "iphrase_match", "prefix", "suffix", "empty"; максимальна глибина вкладеності операторів and і or — 2.

Example:{ "or": [ { "field": "tag", "is": [ "eq", "branded" ] }, { "field": "tag", "is": [ "eq", "competitor" ] } ] }

brand_filterobject

Вираз фільтрації для видимості вашого бренду, що повторює фільтр “Ваш бренд”. brand_name визначає, чи згадується ваш бренд у відповіді: "mentioned" або "not_mentioned". page_status визначає, як ШІ використав ваші сторінки: "cited" (ШІ знайшов сторінки вашого сайту та послався на них у відповіді), "found_but_not_cited" (ШІ знайшов сторінки вашого сайту як потенційні джерела, але не послався на них в остаточній відповіді) або "not_found" (ШІ не знайшов жодної сторінки вашого сайту).
Використовує синтаксис фільтрів з такими обмеженнями: єдиний допустимий оператор — "eq"; кожне поле є окремим розділом: укажіть одне значення або об’єднайте кілька значень одного й того самого поля через or; розділи brand_name і page_status поєднуйте на верхньому рівні через and/or. Вибір усіх значень поля відхиляється, оскільки такий фільтр збігається з усім (натомість не вказуйте це поле).

Example:{ "and": [ { "field": "brand_name", "is": [ "eq", "mentioned" ] }, { "or": [ { "field": "page_status", "is": [ "eq", "cited" ] }, { "field": "page_status", "is": [ "eq", "found_but_not_cited" ] } ] } ] }

volume_rangeobject

Діапазон обсягу для фільтрації.

frominteger

tointeger

changesobject

Потребує date_compared. Залишає лише ті запити, які змінилися одним зі способів, вибраних тут. Три стовпці поєднуються між собою через OR, так само як і значення в межах кожного стовпця, тож пропущений або порожній стовпець нічого не додає до фільтра, а повністю порожній об’єкт залишає кожен запит.

promptarray<string>

Залишати запити, на які дали відповідь лише в одну з двох дат (new, lost) або в обидві (no_change).

Дозволені значення:newlostno_change

mentionsarray<string>

Залишати запити, де набір згаданих у відповіді ваших власних брендів поповнився брендом (new), втратив бренд (lost) або є однаковим в обидві дати (no_change). Конкуренти не враховуються.

Дозволені значення:newlostno_change

citationsarray<string>

Залишати запити, де набір ваших власних доменів, на які є посилання у відповіді, поповнився доменом (new), втратив домен (lost) або є однаковим в обидві дати (no_change). Конкуренти не враховуються.

Дозволені значення:newlostno_change

sentiment_filterobject

Фільтр за тим, як відповіді говорять про ваші бренди та конкурентів, на кшталт фільтра «Тональність» у Brand Radar. Використовує синтаксис фільтрів із трьома полями:

Доступні поля:

brand (обов’язково): назва з brands або competitors, з "eq".
sentiment (необов’язково): positive, neutral, negative або mixed. З "eq" бренд згадується з такою тональністю. З "neq" бренд згадується з тональністю, але ніколи не з такою. З "empty" бренд ніколи не згадується з тональністю, що також включає відповіді, у яких його взагалі не згадано. З not "empty" бренд згадується з певною тональністю. Без sentiment підходить будь-яка відповідь, у якій згадується бренд.
aspect (необов’язково): чого стосується тональність, з "eq": features_specs, performance_effectiveness, price_value, reputation_popularity, quality_reliability, design_comfort, usability_compatibility, availability_delivery, safety_health, service_support або general.
Кожне правило стосується одного бренду: одна умова або and з умов. Щоб поєднувати правила, помістіть кожне в окремий and і з’єднайте їх верхньорівневим and або or.

Example:{ "or": [ { "and": [ { "field": "brand", "is": [ "eq", "Adidas" ] }, { "field": "sentiment", "is": [ "eq", "negative" ] } ] }, { "and": [ { "field": "brand", "is": [ "eq", "Nike" ] }, { "field": "sentiment", "is": [ "eq", "positive" ] }, { "field": "aspect", "is": [ "eq", "price_value" ] } ] } ] }

opinions_firstboolean

Виносить відповіді з позитивною, негативною або змішаною згадкою відстежуваного бренду перед іншими, а в межах кожної групи — за релевантністю, як їх перелічує сторінка «Тональність» у Brand Radar. Лише з order_by relevance.

Default:false

outputstring

Формат виводу.

Дозволені значення:jsonphp

Відповіді

ai_responsesarray<object>

brand_sentimentarray<object>

Кожна згадка відстежуваного бренду у відповіді: спочатку ваші бренди, а потім конкуренти в їхньому порядку, разом із тим, як про них говориться у відповіді.

brandstring

Згаданий відстежуваний бренд.

sentimentstring or null

Яка тональність висловлювання про бренд у цій згадці. Null, якщо дані недоступні.

Дозволені значення:positiveneutralnegativemixednull

aspectstring or null

Про що ця згадка — наприклад, про ціну або якість. Null, якщо дані недоступні.

Дозволені значення:features_specsperformance_effectivenessprice_valuereputation_popularityquality_reliabilitydesign_comfortusability_compatibilityavailability_deliverysafety_healthservice_supportgeneralnull

snippetstring or null

Речення навколо згадки. Null, якщо його неможливо знайти у відповіді.

countrystring

Країна запитання.

data_sourcestring

Модель чатбота, яка згенерувала відповідь.

funnel_stagestring or null

Етап воронки запиту. Null — якщо етап воронки недоступний.

Дозволені значення:awarenessconsiderationdecisionunclearnull

intentarray<string>

Мітки наміру запиту, включно з його основним наміром, підтипами та брендовими/локальними атрибутами. Порожній масив означає, що мітки наміру недоступні.

Дозволені значення:informationalnavigationaltransactionalbrandedcommercialcomparisonhow_tolocalopinionrecommendation

last_updatedstring (date)

Дата останнього оновлення даних.

linksarray<object>

(10 одиниць) Посилання, використані для відповіді.

urlstring

titlestring or null

questionstring

Запитання, поставлене користувачем.

responsestring

(10 одиниць) Відповідь моделі.

search_queriesarray<string>

Пошуковий запит, який чатбот використовує, щоб знайти інформацію для відповіді. Примітка: якщо data_source не містить chatgpt або perplexity, це поле завжди буде порожнім.

statusstring or null

Як запит змінився між date_compared і date. Null, якщо не задано date_compared. new — відповідь надано в date, але не в date_compared. lost — відповідь надано в date_compared, але не в date; решта полів цього рядка описує відповідь за date_compared, оскільки за date її немає. no_change — відповідь надано в обидві дати, що нічого не каже про те, чи змінилися сама відповідь, згадки або цитування.

Дозволені значення:newlostno_changenull

tagsarray<string>

Теги, призначені запиту.

volumeinteger

(10 одиниць) Орієнтовний місячний обсяг пошуку. Це базується на наших оцінках для Google й поєднує обсяги пошуку пов'язаних ключових слів, у яких це запитання з'являється в розділі People Also Ask.