Cytowania

API + MCP

POST/v3/brand-radar/citations-overview

Żą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 obejmujące dane promptu Ahrefs są rozliczane zgodnie ze standardową wyceną jednostek API.

Każdy podmiot podany w brands (oraz w competitors, jeśli dotyczy) musi zawierać co najmniej jedną wartość w url_groups. Podmioty składające się wyłącznie z names nie są tutaj obsługiwane, ponieważ cytowania są dopasowywane do grup adresów URL.

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

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"]}]}

outputstring

Format wyjściowy.

Dozwolone wartości:jsoncsvxmlphp

Odpowiedzi

metricsarray<object>

brandstring

Nazwa marki (Twojej lub konkurenta podanego w żądaniu).

entity_typestring

Określa, czy wiersz reprezentuje wartość zbiorczą, twoją markę docelową czy konkurenta.

Dozwolone wartości:aggregatetargetcompetitor

no_tracked_brandsinteger

Szacowana liczba cytowań w odpowiedziach związanych z określonym rynkiem, w których nie wspomniano żadnych podanych adresów URL marek (wartość wynosi zero, gdy nie określono market).

only_competitors_brandsinteger

Szacowana liczba cytowań w odpowiedziach, w których wspomniano wyłącznie adresy URL marek konkurencji.

only_target_brandinteger

Szacowana liczba cytowań w odpowiedziach, w których wspomniano wyłącznie adresy URL Twojej marki.

target_and_competitors_brandsinteger

Szacowana liczba cytowań w odpowiedziach, w których wspomniano zarówno adresy URL Twojej marki, jak i marek konkurencji.

totalinteger

Łączna szacowana liczba cytowań adresów URL Twojej marki (obejmuje zarówno only_target_brand, jak i target_and_competitors_brands).

curl "https://api.ahrefs.com/v3/brand-radar/citations-overview" \ -X POST \ -H "Authorization: Bearer $AHREFS_API_KEY" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ --data-raw '{ "select": ["field_a","field_b"], "where": {}, "report_id": "string", "brands": [ { "names": ["ahrefs","ahrefs seo"], "url_groups": [ { "target": "ahrefs.com", "scope": "url" } ] } ], "competitors": [ { "names": ["ahrefs","ahrefs seo"], "url_groups": [ { "target": "ahrefs.com", "scope": "url" } ] } ], "content_filter": { "include": ["string"], "exclude": ["string"] }, "data_source": ["chatgpt"], "country": ["ad"], "prompts": "ahrefs", "tags_filter": {"or":[{"field":"tag","is":["eq","branded"]},{"field":"tag","is":["eq","competitor"]}]}, "output": "json" }'

{ "metrics": [ { "brand": "string", "entity_type": "aggregate", "no_tracked_brands": 0, "only_competitors_brands": 0, "only_target_brand": 0, "target_and_competitors_brands": 0, "total": 0 } ] }