Panoramica delle citazioni

Solo API

POST/v3/brand-radar/citations-overview

Le richieste a questo endpoint consumano unità API in base al parametro prompts: le richieste che restituiscono solo dati di prompt personalizzati sono gratuite, mentre quelle che includono dati di prompt di Ahrefs seguono la tariffazione Standard per le unità API.

Ogni entità fornita in brands (e in competitors, quando applicabile) deve includere almeno un valore in url_groups. Le entità costituite solo da names non sono supportate qui, perché le citazioni vengono abbinate ai gruppi di URL.

Corpo della richiesta

whereobject

L’espressione di filtro. Sono riconosciuti i seguenti identificatori di colonna (diversi da quelli riconosciuti dal parametro select).

selectarray<string>Required

Un elenco di campi da restituire.

Example:["field_a","field_b"]

tags_filterobject

Un’espressione di filtro per i tag dei prompt. Richiede report_id. Usa la sintassi dei filtri con le seguenti restrizioni: l’unico nome di campo valido è "tag"; gli unici operatori validi sono: "eq", "neq", "substring", "isubstring", "phrase_match", "iphrase_match", "prefix", "suffix", "empty"; la profondità massima di annidamento di and, or è 2.

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

search_volume_typestring

I report sulla visibilità nell’IA stanno passando al volume rettificato per l’IA. Questo valore stima meglio la domanda di risposte dell’IA nei chatbot e nelle superfici di ricerca basate sull’IA. Viene calcolato rettificando il volume di ricerca di Google in base all’utilizzo stimato di ciascuna piattaforma di IA rispetto a Google. Questo parametro verrà deprecato il 31 agosto 2026; tutte le richieste useranno il nuovo volume rettificato per l’IA.

Valori consentiti:ask_volumekeyword_volume

Default:ask_volume

countryarray<string>

Un elenco di codici paese a due lettere (ISO 3166-1 alpha-2).

Valori consentiti:adaeafagaialamaoarasatauawazba…

Default:[]

report_idstring

L’ID del report da usare. Se ne viene specificato uno, gli altri parametri vengono ricavati dal report (brand, concorrenti, mercato, paese, filtri). Se vengono forniti paese o filtri, questi sovrascrivono quelli del report. Puoi trovarlo nell’URL del tuo report Brand Radar in Ahrefs: https://app.ahrefs.com/brand-radar/reports/#report_id#/...

promptsstring

Il tipo di prompt da usare. Se non specificato, verranno usati entrambi. I prompt personalizzati richiedono che venga fornito un report_id.

Valori consentiti:ahrefscustom

data_sourcearray<string>Required

Un elenco di modelli di chatbot. Tutti i modelli possono essere combinati tra loro. Il modulo claude supporta solo prompt personalizzati.

Valori consentiti:chatgptgoogle_ai_overviewsgoogle_ai_modegeminiperplexitycopilotclaudegrokgoogle_ai_overviews_keywordsgoogle_ai_mode_keywords

marketarray<string>

Un elenco dei mercati di nicchia dei tuoi brand. Deprecato il 2026-05-18, questo parametro non avrà alcun effetto poco dopo questa data.

competitorsarray<object>

Un elenco di nomi e siti web dei concorrenti da cercare.

Default:[]

At least one of names or url_groups is required

namesarray<string>

I nomi del brand/concorrente

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

url_groupsarray<object>

targetstring (domain)required

Il dominio del target

Example:ahrefs.com

scopestringrequired

Ambito del target.

Valori consentiti:urlpathdomainsubdomains

brandsarray<object>

Un elenco di nomi e siti web dei brand da cercare.

Default:[]

At least one of names or url_groups is required

namesarray<string>

I nomi del brand/concorrente

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

url_groupsarray<object>

targetstring (domain)required

Il dominio del target

Example:ahrefs.com

scopestringrequired

Ambito del target.

Valori consentiti:urlpathdomainsubdomains

outputstring

Il formato di output.

Valori consentiti:jsoncsvxmlphp

Risposte

metricsarray<object>

brandstring

Nome del brand (il tuo brand o un concorrente fornito nella richiesta).

no_tracked_brandsinteger

Citazioni stimate dalle risposte relative al mercato specificato che non menzionano nessuno degli URL dei brand forniti (il valore è zero quando market non è specificato).

only_competitors_brandsinteger

Citazioni stimate dalle risposte che menzionano solo gli URL dei brand concorrenti.

only_target_brandinteger

Citazioni stimate dalle risposte che menzionano solo gli URL del tuo brand.

target_and_competitors_brandsinteger

Citazioni stimate dalle risposte che menzionano sia gli URL del tuo brand sia quelli dei brand concorrenti.

totalinteger

Totale delle citazioni stimate per gli URL del tuo brand (include sia only_target_brand sia 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 '{ "where": {}, "select": ["field_a","field_b"], "tags_filter": {"or":[{"field":"tag","is":["eq","branded"]},{"field":"tag","is":["eq","competitor"]}]}, "search_volume_type": "ask_volume", "country": ["ad"], "report_id": "string", "prompts": "ahrefs", "data_source": ["chatgpt"], "market": ["string"], "competitors": [ { "names": ["ahrefs","ahrefs seo"], "url_groups": [ { "target": "ahrefs.com", "scope": "url" } ] } ], "brands": [ { "names": ["ahrefs","ahrefs seo"], "url_groups": [ { "target": "ahrefs.com", "scope": "url" } ] } ], "output": "json" }'

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