주제

API + MCP

GET/v3/content-helper/topics

이 엔드포인트는 요청당 기본 1000 유닛을 소모하며, 점수를 매길 URL을 요청하면 500 유닛이 추가로 소모됩니다.

분석은 해당 키워드로 현재 순위에 있는 페이지를 대상으로 요청 시 실행되므로, 키워드에 대한 첫 요청은 몇 초가 걸립니다. 결과는 캐시되며, 반복 요청은 캐시에서 무료로 제공됩니다.

Ahrefs가 이미 수집한 SERP만 사용하며, 새로운 SERP는 수집하지 않습니다. 지난 90일 이내에 해당 키워드와 국가에 대한 SERP를 수집한 적이 있으면, 이 엔드포인트는 400 오류를 반환하고 유닛은 소모되지 않습니다.

쿼리 매개변수

keywordstring필수

SERP를 분석할 키워드입니다.

countrystring필수

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

허용되는 값:adaeafagaialamaoarasatauawazba…

top_competitorsinteger

분석할 상위 랭킹 페이지 수입니다. 페이지 수가 적을수록 분석은 더 빠르지만, 범위는 줄어듭니다.

기본:10

target_urlstring (url)

(500 유닛) 동일한 토픽을 기준으로 점수를 매길 내 페이지입니다. 예: 작성 중인 초안 또는 개선하려는 페이지. 페이지는 실시간으로 가져옵니다. 매번 추가 API 유닛이 소모됩니다(점수는 캐시되지 않음).

outputstring

출력 형식입니다.

허용되는 값:jsonphp

응답

topicsarray<object>

avg_scorenumber (float)

분석할 수 있었던 페이지를 대상으로, 0~100 범위에서 이 토픽의 평균 커버리지 점수입니다. 값이 높을수록 이미 순위에 있는 페이지들이 해당 토픽을 충분히 다룬다는 뜻입니다. 어떤 페이지도 분석할 수 없었던 경우 null입니다.

descriptionstring

경쟁 페이지에서 식별된 핵심 토픽의 내용입니다.

pagesarray<object>

이 토픽의 페이지별 커버리지: url, position(페이지의 SERP 순위), score(0~100), extracts(토픽을 다루는 페이지의 발췌문) 필드를 가진 레코드입니다. 콘텐츠를 가져올 수 없었던 페이지의 경우 score와 extracts는 null 및 빈 값이며, 이는 점수가 0인 페이지와는 구별됩니다.

urlstring (url)

positioninteger

scoreinteger

extractsarray<string>

pages_coveringinteger

분석한 페이지 중 이 토픽을 조금이라도 다루는 페이지 수(0이 아닌 점수)입니다.

serp_datestring (date)

분석한 SERP가 수집된 시점입니다.

targetobject or null

target_url로 지정된 페이지가 이 토픽을 어떻게 다루는지입니다. target_url이 제공되지 않은 경우 null입니다.

urlstring (url)

scoreinteger

extractsarray<string>

topicstring

상위 랭킹 페이지에서 다루는 핵심 토픽의 이름입니다.