Topik

API + MCPKhusus Enterprise

POST/v3/brand-radar/topics

Permintaan ke endpoint ini akan menghabiskan unit API berdasarkan parameter prompts: permintaan yang hanya mengembalikan data prompt kustom gratis, sedangkan permintaan yang menyertakan data prompt Ahrefs mengikuti penetapan harga unit API Standard.

Isi permintaan

selectarray<string>Required

Daftar kolom yang akan dikembalikan.

Field yang tersedia:

country
mentions
responses
topic
volume

Example:["field_a","field_b"]

whereobject

Ekspresi filter. Pengenal kolom berikut dikenali (ini berbeda dari pengenal yang dikenali oleh parameter select).

report_idstring

ID laporan yang akan digunakan. Jika ID diberikan, parameter lainnya diambil dari laporan (brand, competitors, market, country, filters). Jika country atau filters disediakan, parameter tersebut akan menggantikan yang ada di laporan. Anda dapat menemukannya di URL laporan Brand Radar Anda di Ahrefs: https://app.ahrefs.com/brand-radar/reports/#report_id#/...

brandsarray<object>

Daftar nama merek dan situs web yang akan dicari.

Default:[]

At least one of names or url_groups is required

namesarray<string>

Nama merek/pesaing

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

url_groupsarray<object>

targetstring (domain)required

Domain target

Example:ahrefs.com

scopestringrequired

Cakupan target.

Nilai yang diizinkan:urlpathdomainsubdomains

competitorsarray<object>

Daftar nama kompetitor dan situs web yang akan dicari.

Default:[]

At least one of names or url_groups is required

namesarray<string>

Nama merek/pesaing

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

url_groupsarray<object>

targetstring (domain)required

Domain target

Example:ahrefs.com

scopestringrequired

Cakupan target.

Nilai yang diizinkan:urlpathdomainsubdomains

content_filterobject

Frasa opsional yang digunakan untuk menyertakan atau mengecualikan hasil berdasarkan kontennya.

includearray<string>

Hanya tampilkan hasil yang berisi setidaknya salah satu dari frasa yang sama persis berikut.

excludearray<string>

Sembunyikan hasil yang berisi salah satu dari frasa yang sama persis berikut.

data_sourcearray<string>Required

Daftar model chatbot. Semua model dapat dikombinasikan satu sama lain. Modul claude hanya mendukung prompt kustom.
Model google_ai_overviews_keywords dan google_ai_mode_keywords melaporkan visibilitas AI Overviews / AI Mode yang diperoleh dari kueri pencarian Google (kata kunci), bukan dari prompt.

Nilai yang diizinkan:chatgptgoogle_ai_overviewsgoogle_ai_modegeminiperplexitycopilotclaudegrokgoogle_ai_overviews_keywordsgoogle_ai_mode_keywords

countryarray<string>

Daftar kode negara dua huruf (ISO 3166-1 alpha-2).

Nilai yang diizinkan:adaeafagaialamaoarasatauawazba…

Default:[]

promptsstring

Jenis prompt yang akan digunakan. Jika tidak ditentukan, keduanya akan digunakan. Prompt kustom mengharuskan report_id disertakan.

Nilai yang diizinkan:ahrefscustom

limitinteger

Jumlah hasil yang akan dikembalikan.

Default:1000

datestring (date)

Tanggal yang akan dicari dalam format YYYY-MM-DD.

date_fromstring (date)

Tanggal mulai periode historis dalam format YYYY-MM-DD.

date_tostring (date)

Tanggal akhir periode historis dalam format YYYY-MM-DD.

tags_filterobject

Ekspresi filter untuk tag prompt. Memerlukan report_id. Menggunakan sintaks filter dengan batasan berikut: satu-satunya nama field yang valid adalah "tag"; operator yang valid hanyalah: "eq", "neq", "substring", "isubstring", "phrase_match", "iphrase_match", "prefix", "suffix", "empty"; kedalaman nesting maksimum untuk and dan or adalah 2.

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

brand_filterobject

Ekspresi filter untuk visibilitas merek Anda, yang mencerminkan filter “Your brand”. brand_name mencocokkan respons berdasarkan apakah respons tersebut menyebutkan merek Anda: "mentioned" atau "not_mentioned". page_status mencocokkan berdasarkan cara AI menggunakan halaman Anda: "cited" (AI mengambil halaman dari situs Anda dan merujuknya dalam jawaban), "found_but_not_cited" (AI mengambil halaman dari situs Anda sebagai sumber potensial, tetapi tidak merujuknya dalam jawaban akhir), atau "not_found" (AI tidak mengambil halaman apa pun dari situs Anda).
Menggunakan sintaks filter dengan batasan berikut: satu-satunya operator yang valid adalah "eq"; setiap field adalah satu bagian: berikan satu nilai, atau gabungkan beberapa nilai dari field yang sama dengan or; gabungkan bagian brand_name dan page_status dengan and/or tingkat teratas. Memilih semua nilai dari sebuah field akan ditolak karena cocok dengan semuanya (abaikan field tersebut).

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

Rentang volume yang akan difilter.

frominteger

tointeger

outputstring

Format output.

Nilai yang diizinkan:jsonphp

Respons

topicsarray<object>

countrystring

Negara yang terkait dengan topik. Saat tidak ada topik induk yang teridentifikasi, ini adalah satu-satunya negara yang dipilih, atau all jika beberapa atau semua negara dipilih.

mentionsarray<object>

Jumlah respons untuk merek yang dilacak dan setiap kompetitor.

entitystring

Merek yang dilacak atau kompetitor.

responsesinteger

Jumlah respons AI yang menyebut entitas tersebut.

responsesinteger

Jumlah respons AI yang terkait dengan topik tersebut.

topicstring or null

Topik induk. Bernilai null saat tidak ada topik induk yang teridentifikasi.

volumeinteger or null

Perkiraan volume pencarian bulanan untuk topik tersebut.

curl "https://api.ahrefs.com/v3/brand-radar/topics" \ -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", "limit": 0, "date": "string", "date_from": "string", "date_to": "string", "tags_filter": {"or":[{"field":"tag","is":["eq","branded"]},{"field":"tag","is":["eq","competitor"]}]}, "brand_filter": {"and":[{"field":"brand_name","is":["eq","mentioned"]},{"or":[{"field":"page_status","is":["eq","cited"]},{"field":"page_status","is":["eq","found_but_not_cited"]}]}]}, "volume_range": { "from": 0, "to": 0 }, "output": "json" }'

{ "topics": [ { "country": "string", "mentions": [ { "entity": "string", "responses": 0 } ], "responses": 0, "topic": "string", "volume": 0 } ] }