Docs
문서 검색...⌘K

주제

API + MCP엔터프라이즈 전용
POST/v3/brand-radar/topics

이 엔드포인트로 보내는 요청은 prompts 매개변수에 따라 API 유닛을 소모합니다. 사용자 정의 프롬프트 데이터만 반환하는 요청은 무료이며, Ahrefs 프롬프트 데이터를 포함하는 요청에는 스탠다드 API 유닛 요금이 적용됩니다.

요청 본문

selectarray<string>Required

반환할 필드 목록입니다.

사용 가능한 필드:
  • country
  • mentions
  • responses
  • topic
  • volume
Example:["field_a","field_b"]
whereobject

필터 표현식입니다. 다음 열 식별자가 인식됩니다(이는 select 매개변수에서 인식되는 식별자와 다릅니다).

report_idstring

사용할 보고서의 ID입니다. ID가 제공되면 다른 파라미터(brand, competitors, market, country, filters)는 보고서에서 가져옵니다. country 또는 filters가 제공되면 보고서의 값을 덮어씁니다. Ahrefs의 브랜드 레이더 보고서 URL에서 확인할 수 있습니다: https://app.ahrefs.com/brand-radar/reports/#report_id#/...

brandsarray<object>

검색할 브랜드 이름과 웹사이트 목록입니다.

Default:[]
At least one of names or url_groups is required
namesarray<string>

브랜드/경쟁사 이름입니다.

Example:["ahrefs","ahrefs seo"]
url_groupsarray<object>
targetstring (domain)required

대상의 도메인입니다.

Example:ahrefs.com
scopestringrequired

대상의 범위입니다.

허용되는 값:urlpathdomainsubdomains
competitorsarray<object>

검색할 경쟁사 이름과 웹사이트 목록입니다.

Default:[]
At least one of names or url_groups is required
namesarray<string>

브랜드/경쟁사 이름입니다.

Example:["ahrefs","ahrefs seo"]
url_groupsarray<object>
targetstring (domain)required

대상의 도메인입니다.

Example:ahrefs.com
scopestringrequired

대상의 범위입니다.

허용되는 값:urlpathdomainsubdomains
content_filterobject

콘텐츠에 따라 결과를 포함하거나 제외하는 데 사용되는 선택적 문구입니다.

includearray<string>

다음의 정확히 일치하는 문구 중 하나 이상을 포함하는 결과만 표시합니다.

excludearray<string>

다음의 정확히 일치하는 문구 중 하나라도 포함하는 결과를 숨깁니다.

data_sourcearray<string>Required

챗봇 모델 목록입니다. 모든 모델은 서로 함께 사용할 수 있습니다. claude 모듈은 사용자 정의 프롬프트만 지원합니다.
google_ai_overviews_keywords 및 google_ai_mode_keywords 모델은 프롬프트가 아닌 Google 검색 쿼리(키워드)에서 도출된 AI 개요/AI 모드 가시성을 보고합니다.

허용되는 값:chatgptgoogle_ai_overviewsgoogle_ai_modegeminiperplexitycopilotclaudegrokgoogle_ai_overviews_keywordsgoogle_ai_mode_keywords
countryarray<string>

두 글자 국가 코드(ISO 3166-1 alpha-2) 목록입니다.

허용되는 값:adaeafagaialamaoarasatauawazba…
Default:[]
promptsstring

사용할 프롬프트 유형입니다. 지정하지 않으면 둘 다 사용됩니다. 사용자 정의 프롬프트를 사용하려면 report_id를 제공해야 합니다.

허용되는 값:ahrefscustom
limitinteger

반환할 결과 수입니다.

Default:1000
datestring (date)

YYYY-MM-DD 형식으로 검색할 날짜입니다.

date_fromstring (date)

YYYY-MM-DD 형식의 과거 기간 시작일입니다.

date_tostring (date)

YYYY-MM-DD 형식의 과거 기간 종료일입니다.

tags_filterobject

프롬프트 태그에 대한 필터 표현식입니다. report_id가 필요합니다. 다음 제한 사항이 적용되는 필터 문법을 사용합니다: 유효한 필드 이름은 "tag"뿐입니다. 유효한 연산자는 다음뿐입니다: "eq", "neq", "substring", "isubstring", "phrase_match", "iphrase_match", "prefix", "suffix", "empty". and와 or의 최대 중첩 깊이는 2입니다.

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

브랜드 가시성에 대한 필터 표현식으로, “내 브랜드” 필터와 동일하게 동작합니다. brand_name은 응답에서 브랜드가 언급되었는지 여부를 매칭합니다: "mentioned" 또는 "not_mentioned". page_status는 AI가 페이지를 사용한 방식을 매칭합니다: "cited"(AI가 사이트의 페이지를 가져와 답변에서 참조함), "found_but_not_cited"(AI가 사이트의 페이지를 잠재적 출처로 가져왔지만 최종 답변에서는 참조하지 않음), 또는 "not_found"(AI가 사이트에서 페이지를 전혀 가져오지 않음).
다음 제한 사항이 적용되는 필터 문법을 사용합니다: 유효한 연산자는 "eq"뿐입니다. 각 필드는 하나의 섹션입니다. 단일 값을 지정하거나 같은 필드의 여러 값을 or로 결합하세요. brand_name과 page_status 섹션은 최상위 and/or로 연결하세요. 필드의 모든 값을 선택하면 모든 항목과 일치하므로 거부됩니다(대신 해당 필드를 생략하세요).

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

필터링에 사용할 검색량 범위입니다.

frominteger
tointeger
outputstring

출력 형식입니다.

허용되는 값:jsonphp

응답

topicsarray<object>
countrystring

주제와 연결된 국가입니다. 상위 주제가 식별되지 않은 경우 이 값은 유일하게 선택된 국가이거나, 여러 국가 또는 모든 국가가 선택된 경우 all입니다.

mentionsarray<object>

추적 중인 브랜드와 각 경쟁사에 대한 응답 수입니다.

entitystring

추적 중인 브랜드 또는 경쟁사입니다.

responsesinteger

해당 엔티티가 언급된 AI 응답 수입니다.

responsesinteger

해당 주제와 관련된 AI 응답 수입니다.

topicstring or null

상위 주제입니다. 상위 주제가 식별되지 않은 경우 null입니다.

volumeinteger or null

주제의 추정 월간 검색량입니다.