Odpowiedzi AI

API + MCP

POST/v3/brand-radar/ai-responses

Żądania do tego punktu końcowego zużywają jednostki API w zależności od parametru prompts: żądania zwracające wyłącznie dane niestandardowego promptu są bezpłatne, natomiast żądania uwzględniające dane promptów Ahrefs są rozliczane zgodnie ze standardowym cennikiem jednostek API.

Treść żądania

selectarray<string>Required

Lista pól do zwrócenia.

Example:["field_a","field_b"]

whereobject

Wyrażenie filtra. Rozpoznawane są następujące identyfikatory kolumn (różnią się od identyfikatorów rozpoznawanych przez parametr select).

report_idstring

ID raportu, którego należy użyć. Jeśli zostanie podane, pozostałe parametry są pobierane z raportu (marka, konkurenci, rynek, kraj, filtry). Jeśli podano kraj lub filtry, zastępują one wartości z raportu. Znajdziesz je w adresie URL raportu Brand Radar w Ahrefs: https://app.ahrefs.com/brand-radar/reports/#report_id#/...

brandsarray<object>

Lista nazw marek i stron internetowych do wyszukania.

Default:[]

At least one of names or url_groups is required

namesarray<string>

Nazwy marki/konkurenta

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

url_groupsarray<object>

targetstring (domain)required

Domena celu

Example:ahrefs.com

scopestringrequired

Zakres celu.

Dozwolone wartości:urlpathdomainsubdomains

competitorsarray<object>

Lista nazw konkurentów i stron internetowych do wyszukania.

Default:[]

At least one of names or url_groups is required

namesarray<string>

Nazwy marki/konkurenta

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

url_groupsarray<object>

targetstring (domain)required

Domena celu

Example:ahrefs.com

scopestringrequired

Zakres celu.

Dozwolone wartości:urlpathdomainsubdomains

content_filterobject

Opcjonalne frazy służące do uwzględniania lub wykluczania wyników na podstawie ich treści.

includearray<string>

Wyświetlaj tylko wyniki zawierające co najmniej jedną z tych dokładnych fraz.

excludearray<string>

Ukrywaj wyniki zawierające dowolną z tych dokładnych fraz.

data_sourcearray<string>Required

Lista modeli chatbotów. Wszystkie modele można łączyć ze sobą. Moduł claude obsługuje wyłącznie niestandardowe prompty.
Modele google_ai_overviews_keywords i google_ai_mode_keywords raportują widoczność w AI Overviews / AI Mode określoną na podstawie zapytań w wyszukiwarce Google (słów kluczowych), a nie promptów.

Dozwolone wartości:chatgptgoogle_ai_overviewsgoogle_ai_modegeminiperplexitycopilotclaudegrokgoogle_ai_overviews_keywordsgoogle_ai_mode_keywords

countryarray<string>

Lista dwuliterowych kodów krajów (ISO 3166-1 alpha-2).

Dozwolone wartości:adaeafagaialamaoarasatauawazba…

Default:[]

promptsstring

Typ promptów do użycia. Jeśli nie określono, użyte zostaną oba. Niestandardowe prompty wymagają podania report_id.

Dozwolone wartości:ahrefscustom

limitinteger

Liczba wyników do zwrócenia.

Default:1000

datestring (date)

Data, dla której ma zostać wykonane wyszukiwanie, w formacie YYYY-MM-DD.

date_comparedstring (date)

Data do porównania z date, w formacie YYYY-MM-DD. Musi być ściśle wcześniejsza niż date. Po ustawieniu raport obejmuje każdy prompt, na który udzielono odpowiedzi w którymkolwiek z tych dni, a pole status informuje, jak każdy z nich zmienił się między tymi datami. Prompt, na który odpowiedziano tylko w date_compared, jest raportowany jako lost, a pozostałe pola opisują jego odpowiedź z date_compared, ponieważ nie ma jej dla date.

order_by

Jak sortować wyniki: według kolumny lub według tego, jak odpowiedzi mówią o jednej marce, tak jak umożliwia to strona Sentyment w Brand Radar.

Kolumna do sortowania wyników.

Dozwolone wartości:relevancevolume

tags_filterobject

Wyrażenie filtra tagów promptu. Wymaga report_id. Wykorzystuje składnię filtrów z następującymi ograniczeniami: jedyną dozwoloną nazwą pola jest "tag"; jedyne dozwolone operatory to: "eq", "neq", "substring", "isubstring", "phrase_match", "iphrase_match", "prefix", "suffix", "empty"; maksymalna głębokość zagnieżdżenia operatorów and i or wynosi 2.

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

brand_filterobject

Wyrażenie filtra widoczności Twojej marki, odpowiadające filtrowi „Twoja marka”. brand_name określa, czy odpowiedź wspomina Twoją markę: "mentioned" lub "not_mentioned". page_status określa, w jaki sposób AI wykorzystała Twoje strony: "cited" (AI pobrała strony z Twojej witryny i odwołała się do nich w odpowiedzi), "found_but_not_cited" (AI pobrała strony z Twojej witryny jako potencjalne źródła, ale nie odwołała się do nich w końcowej odpowiedzi) lub "not_found" (AI nie pobrała żadnych stron z Twojej witryny).
Wykorzystuje składnię filtrów z następującymi ograniczeniami: jedynym dozwolonym operatorem jest "eq"; każde pole stanowi jedną sekcję: podaj jedną wartość albo połącz kilka wartości tego samego pola za pomocą or; sekcje brand_name i page_status połącz na najwyższym poziomie za pomocą and/or. Wybranie wszystkich wartości pola zostanie odrzucone, ponieważ pasuje do wszystkiego (zamiast tego pomiń pole).

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

Zakres wolumenu do filtrowania.

frominteger

tointeger

changesobject

Wymaga date_compared. Pozostawia tylko prompty, które zmieniły się w jeden z wybranych tutaj sposobów. Te trzy kolumny są łączone operatorem OR, podobnie jak wartości w obrębie każdej kolumny, więc pominięta lub pusta kolumna nie wnosi nic do filtra, a całkowicie pusty obiekt zachowuje każdy prompt.

promptarray<string>

Zachowaj prompty, na które udzielono odpowiedzi tylko dla jednej z dwóch dat (new, lost) albo dla obu (no_change).

Dozwolone wartości:newlostno_change

mentionsarray<string>

Zachowaj prompty, w których zbiór Twoich własnych marek wspomnianych w odpowiedzi zyskał markę (new), stracił jedną (lost) albo jest identyczny dla obu dat (no_change). Konkurenci nie są brani pod uwagę.

Dozwolone wartości:newlostno_change

citationsarray<string>

Zachowaj prompty, w których zbiór Twoich własnych domen cytowanych w odpowiedzi zyskał domenę (new), stracił jedną (lost) albo jest identyczny dla obu dat (no_change). Konkurenci nie są brani pod uwagę.

Dozwolone wartości:newlostno_change

sentiment_filterobject

Filtr określający, jak odpowiedzi wypowiadają się o Twoich markach i konkurentach, podobnie jak filtr „Sentyment” w Brand Radar. Używa składni filtrów z trzema polami:

Dostępne pola:

brand (wymagane): nazwa z brands lub competitors, z "eq".
sentiment (opcjonalne): positive, neutral, negative lub mixed. Z "eq" marka jest wspominana z takim sentymentem. Z "neq" marka jest wspominana z jakimś sentymentem, ale nigdy z tym konkretnym. Z "empty" marka nigdy nie jest wspominana z sentymentem, co obejmuje odpowiedzi, które jej nie wspominają. Z not "empty" marka jest wspominana z jakimś sentymentem. Bez sentiment pasuje każda odpowiedź, która wspomina markę.
aspect (opcjonalne): czego dotyczy sentyment, z "eq": features_specs, performance_effectiveness, price_value, reputation_popularity, quality_reliability, design_comfort, usability_compatibility, availability_delivery, safety_health, service_support lub general.
Każda reguła dotyczy jednej marki i zawiera jeden warunek albo zestaw warunków połączonych operatorem and. Aby połączyć reguły, umieść każdą z nich we własnym and i połącz je nadrzędnym operatorem and lub 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

Umieszcza odpowiedzi z pozytywną, negatywną lub mieszaną wzmianką o śledzonej marce przed pozostałymi, a w każdej grupie sortuje według trafności — tak jak są one wyświetlane na stronie „Sentyment” w Brand Radar. Tylko z order_by relevance.

Default:false

outputstring

Format wyjściowy.

Dozwolone wartości:jsonphp

Odpowiedzi

ai_responsesarray<object>

brand_sentimentarray<object>

Każda wzmianka o śledzonej marce w odpowiedzi — najpierw Twoje marki, a potem konkurenci w ich kolejności — wraz z tym, jak odpowiedź się o niej wypowiada.

brandstring

Wspomniana śledzona marka.

sentimentstring or null

Jak odpowiedź wypowiada się o marce w tej wzmiance. Null, gdy nie jest dostępne.

Dozwolone wartości:positiveneutralnegativemixednull

aspectstring or null

Czego dotyczy wzmianka, np. ceny lub jakości. Null, gdy nie jest dostępne.

Dozwolone wartości:features_specsperformance_effectivenessprice_valuereputation_popularityquality_reliabilitydesign_comfortusability_compatibilityavailability_deliverysafety_healthservice_supportgeneralnull

snippetstring or null

Zdanie z odpowiedzi, w którym znajduje się wzmianka. Null, gdy nie można znaleźć takiego zdania w odpowiedzi.

countrystring

Kraj, którego dotyczy pytanie.

data_sourcestring

Model chatbota, który wygenerował odpowiedź.

funnel_stagestring or null

Etap lejka promptu. Wartość null, gdy etap lejka nie jest dostępny.

Dozwolone wartości:awarenessconsiderationdecisionunclearnull

intentarray<string>

Etykiety intencji promptu, w tym jego główna intencja, podtypy oraz atrybuty markowe/lokalne. Pusta tablica oznacza, że nie są dostępne żadne etykiety intencji.

Dozwolone wartości:informationalnavigationaltransactionalbrandedcommercialcomparisonhow_tolocalopinionrecommendation

last_updatedstring (date)

Data ostatniej aktualizacji danych.

linksarray<object>

(10 jednostek) Linki użyte w odpowiedzi.

urlstring

titlestring or null

questionstring

Pytanie zadane przez użytkownika.

responsestring

(10 jednostek) Odpowiedź z modelu.

search_queriesarray<string>

Zapytanie wyszukiwawcze użyte przez chatbota do znalezienia informacji potrzebnych do odpowiedzi. Uwaga: jeśli data_source nie zawiera chatgpt ani perplexity, to pole zawsze będzie puste.

statusstring or null

Jak prompt zmienił się między date_compared a date. Wartość null, jeśli nie ustawiono date_compared. new — prompt, na który udzielono odpowiedzi w date, ale nie w date_compared. lost — prompt, na który udzielono odpowiedzi w date_compared, ale nie w date; pozostała część tego wiersza opisuje odpowiedź z date_compared, ponieważ nie ma jej dla date. no_change — prompt, na który udzielono odpowiedzi dla obu dat, co nie mówi nic o tym, czy zmieniła się sama odpowiedź, jej wzmianki lub cytowania.

Dozwolone wartości:newlostno_changenull

tagsarray<string>

Tagi przypisane do zapytania.

volumeinteger

(10 jednostek) Szacowana liczba wyszukiwań miesięcznie. Wartość oparta na naszych estymacjach dla Google, wyliczona poprzez połączenie wolumenów wyszukiwań powiązanych słów kluczowych, w których to pytanie pojawia się w sekcji People Also Ask.