Yapay Zekâ Yanıtları

API + MCP

POST/v3/brand-radar/ai-responses

Bu uç noktaya yapılan istekler, prompts parametresine göre API birimleri tüketir: yalnızca özel istem verisi döndüren istekler ücretsizdir; Ahrefs istem verisini içeren istekler ise standart API birim ücretlendirmesine tabidir.

İstek gövdesi

selectarray<string>Required

Döndürülecek alanların listesi.

Example:["field_a","field_b"]

whereobject

Filtre ifadesi. Aşağıdaki sütun tanımlayıcıları tanınır (bu, select parametresi tarafından tanınan tanımlayıcılardan farklıdır).

report_idstring

Kullanılacak raporun ID’si. Bir rapor verilirse diğer parametreler rapordan alınır (marka, rakipler, pazar, ülke, filtreler). Ülke veya filtreler sağlanırsa rapordakilerin yerine geçer. Bunu, Ahrefs’teki Brand Radar raporunuzun URL’sinde bulabilirsiniz: https://app.ahrefs.com/brand-radar/reports/#report_id#/...

brandsarray<object>

Aranacak marka adları ve web sitelerinin listesi.

Default:[]

At least one of names or url_groups is required

namesarray<string>

Marka/rakip adları

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

url_groupsarray<object>

targetstring (domain)required

Hedefin alan adı

Example:ahrefs.com

scopestringrequired

Hedefin kapsamı.

İzin verilen değerler:urlpathdomainsubdomains

competitorsarray<object>

Aranacak rakip adları ve web sitelerinin listesi.

Default:[]

At least one of names or url_groups is required

namesarray<string>

Marka/rakip adları

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

url_groupsarray<object>

targetstring (domain)required

Hedefin alan adı

Example:ahrefs.com

scopestringrequired

Hedefin kapsamı.

İzin verilen değerler:urlpathdomainsubdomains

content_filterobject

İçeriklerine göre sonuçları dahil etmek veya hariç tutmak için kullanılan isteğe bağlı ifadeler.

includearray<string>

Yalnızca bu tam ifadelerden en az birini içeren sonuçları göster.

excludearray<string>

Bu tam ifadelerden herhangi birini içeren sonuçları gizle.

data_sourcearray<string>Required

Sohbet botu modellerinin listesi. Tüm modeller birbiriyle birlikte kullanılabilir. claude modülü yalnızca özel istemleri destekler.
google_ai_overviews_keywords ve google_ai_mode_keywords modelleri, istemlerden ziyade Google arama sorgularından (anahtar kelimelerden) elde edilen AI Overviews / AI Mode görünürlüğünü raporlar.

İzin verilen değerler:chatgptgoogle_ai_overviewsgoogle_ai_modegeminiperplexitycopilotclaudegrokgoogle_ai_overviews_keywordsgoogle_ai_mode_keywords

countryarray<string>

İki harfli ülke kodlarının (ISO 3166-1 alfa-2) listesi.

İzin verilen değerler:adaeafagaialamaoarasatauawazba…

Default:[]

promptsstring

Kullanılacak istem türü. Belirtilmezse her ikisi de kullanılır. Özel istemler için bir report_id sağlanması gerekir.

İzin verilen değerler:ahrefscustom

limitinteger

Döndürülecek sonuç sayısı.

Default:1000

datestring (date)

YYYY-MM-DD biçiminde aranacak tarih.

date_comparedstring (date)

date ile karşılaştırılacak tarih (YYYY-MM-DD biçiminde). date değerinden kesinlikle daha erken olmalıdır. Ayarlandığında rapor, iki tarihten herhangi birinde yanıtlanan her istemi kapsar ve status alanı her birinin bu iki tarih arasında nasıl değiştiğini raporlar. Yalnızca date_compared tarihinde yanıtlanan bir istem lost olarak raporlanır; diğer alanlarının geri kalanı ise date_compared yanıtını açıklar, çünkü date tarihinde buna ait bir yanıt yoktur.

order_by

Sonuçların nasıl sıralanacağı: bir sütuna göre veya Brand Radar’daki Duygu Analizi sayfasının yapabildiği gibi, yanıtların bir marka hakkında nasıl konuştuğuna göre.

Sonuçları sıralamak için kullanılacak bir sütun.

İzin verilen değerler:relevancevolume

tags_filterobject

İstem etiketleri için bir filtre ifadesi. report_id gereklidir. Şu kısıtlamalarla filtre söz dizimini kullanır: geçerli tek alan adı "tag"’dir; geçerli operatörler yalnızca şunlardır: "eq", "neq", "substring", "isubstring", "phrase_match", "iphrase_match", "prefix", "suffix", "empty"; and ve or için maksimum iç içe geçme derinliği 2’dir.

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

brand_filterobject

Markanızın görünürlüğüne yönelik, “Markanız” filtresini yansıtan bir filtre ifadesi. brand_name, bir yanıtın markanızdan bahsedip bahsetmediğine göre eşleşir: "mentioned" veya "not_mentioned". page_status, yapay zekânın sayfalarınızı nasıl kullandığına göre eşleşir: "cited" (yapay zekâ sitenizdeki sayfalara erişti ve yanıtta bunlara atıfta bulundu), "found_but_not_cited" (yapay zekâ sitenizdeki sayfalara olası kaynaklar olarak erişti ancak nihai yanıtta bunlara atıfta bulunmadı) veya "not_found" (yapay zekâ sitenizdeki hiçbir sayfaya erişmedi).
Şu kısıtlamalarla filtre söz dizimini kullanır: geçerli tek operatör "eq"’dir; her alan ayrı bir bölümdür: tek bir değer verin veya aynı alanın birden fazla değerini or ile birleştirin; brand_name ve page_status bölümlerini en üst düzeyde bir and/or ile birleştirin. Bir alanın tüm değerlerini seçmek, her şeyle eşleşeceği için kabul edilmez (bunun yerine alanı tamamen atlayın).

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

Filtreleme için kullanılacak hacim aralığı.

frominteger

tointeger

changesobject

date_compared gerektirir. Burada seçilen yöntemlerden biriyle değişen istemleri tutar. Üç sütun birbirine göre OR’lanır; her sütunun içindeki değerler de kendi içinde OR’lanır. Bu nedenle atlanan veya boş bir sütun filtreye hiçbir şey eklemez; tamamen boş bir nesne ise her istemi tutar.

promptarray<string>

Yalnızca iki tarihten birinde yanıtlanan (new, lost) veya her ikisinde de yanıtlanan (no_change) istemleri tutar.

İzin verilen değerler:newlostno_change

mentionsarray<string>

Yanıtta adı geçen kendi markalarınız kümesinin bir marka kazandığı (new), bir marka kaybettiği (lost) veya iki tarihte de aynı olduğu (no_change) istemleri tutar. Rakipler dikkate alınmaz.

İzin verilen değerler:newlostno_change

citationsarray<string>

Yanıt tarafından alıntılanan kendi alan adlarınız kümesinin bir alan adı kazandığı (new), bir alan adı kaybettiği (lost) veya iki tarihte de aynı olduğu (no_change) istemleri tutar. Rakipler dikkate alınmaz.

İzin verilen değerler:newlostno_change

sentiment_filterobject

Yanıtların markalarınız ve rakipleriniz hakkında nasıl konuştuğuna dair bir filtre; Brand Radar’daki Duygu (Sentiment) filtresi gibi. Üç alanla birlikte filtre söz dizimini kullanır:

Mevcut alanlar:

brand (gerekli): brands veya competitors içinden bir ad; "eq" ile.
sentiment (isteğe bağlı): positive, neutral, negative veya mixed. "eq" ile marka bu duygu ile anılır. "neq" ile marka bir duygu ile anılır, ancak asla bu duygu ile değil. "empty" ile marka hiçbir duygu ile anılmaz; buna markanın hiç anılmadığı yanıtlar da dahildir. not "empty" ile marka bir duygu ile anılır. sentiment olmadan, markadan bahseden herhangi bir yanıt eşleşir.
aspect (isteğe bağlı): duyguya konu olan şey; "eq" ile: features_specs, performance_effectiveness, price_value, reputation_popularity, quality_reliability, design_comfort, usability_compatibility, availability_delivery, safety_health, service_support veya general.
Her kural tek bir marka ile ilgilidir: tek bir koşul veya koşulların and ile birleşimi. Kuralları birleştirmek için her birini kendi and ifadesine koyun ve bunları en üst düzeyde bir and veya or ile birleştirin.

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’daki Duygu (Sentiment) sayfasının listelediği gibi, izlenen bir markaya dair pozitif, negatif veya karma bir bahsi olan yanıtları diğerlerinden önce getirir; her grup alaka düzeyine göre sıralanır. Yalnızca order_by relevance ile.

Default:false

outputstring

Çıktı formatı.

İzin verilen değerler:jsonphp

Yanıtlar

ai_responsesarray<object>

brand_sentimentarray<object>

Yanıtta izlenen bir markaya dair her bahis; önce markalarınız, ardından rakipler kendi sıralarıyla ve yanıtın bu marka hakkında nasıl konuştuğu bilgisiyle birlikte.

brandstring

Bahsi geçen izlenen marka.

sentimentstring or null

Yanıtın bu bahiste marka hakkında nasıl konuştuğu. Mevcut olmadığında null olur.

İzin verilen değerler:positiveneutralnegativemixednull

aspectstring or null

Bahsin neyle ilgili olduğu; örneğin fiyat veya kalite. Mevcut olmadığında null olur.

İzin verilen değerler:features_specsperformance_effectivenessprice_valuereputation_popularityquality_reliabilitydesign_comfortusability_compatibilityavailability_deliverysafety_healthservice_supportgeneralnull

snippetstring or null

Bahsin etrafındaki cümle. Yanıtta bulunamadığında null olur.

countrystring

Sorunun ülkesi.

data_sourcestring

Yanıtı üreten sohbet botu modeli.

funnel_stagestring or null

İstemin huni aşaması. Huni aşaması mevcut değilse null olur.

İzin verilen değerler:awarenessconsiderationdecisionunclearnull

intentarray<string>

İstemin birincil amacı, alt türleri ve markalı/yerel özellikleri dâhil olmak üzere amaç etiketleri. Boş bir dizi, amaç etiketi bulunmadığı anlamına gelir.

İzin verilen değerler:informationalnavigationaltransactionalbrandedcommercialcomparisonhow_tolocalopinionrecommendation

last_updatedstring (date)

Verilerin en son güncellendiği tarih.

linksarray<object>

(10 birim) Yanıt için kullanılan bağlantılar.

urlstring

titlestring or null

questionstring

Kullanıcının sorduğu soru.

responsestring

(10 birim) Modelin yanıtı.

search_queriesarray<string>

Sohbet botunun yanıt için bilgi bulmak üzere kullandığı arama sorgusu. Not: data_source içinde chatgpt veya perplexity yoksa bu alan her zaman boş olur.

statusstring or null

İstemin date_compared ile date arasında nasıl değiştiği. date_compared ayarlanmadıkça null olur. new — date tarihinde yanıtlandı ama date_compared tarihinde yanıtlanmadı. lost — date_compared tarihinde yanıtlandı ama date tarihinde yanıtlanmadı; bu satırın geri kalanı, date tarihinde yanıt olmadığı için date_compared yanıtını açıklar. no_change — her iki tarihte de yanıtlandı; bu, yanıtın kendisinin, bahsettiklerinin veya alıntılarının değişip değişmediğine dair bir şey söylemez.

İzin verilen değerler:newlostno_changenull

tagsarray<string>

Sorguya atanan etiketler.

volumeinteger

(10 birim) Tahmini aylık arama hacmi. Bu değer, Google için yaptığımız tahminlere dayanır ve bu sorunun "People Also Ask" bölümünde göründüğü ilgili anahtar kelimelerin arama hacimlerinin birleştirilmesiyle hesaplanır.