seo/
ranked-keywords

도메인, 서브도메인 또는 페이지 하나가 검색 시장에서 노출되는 키워드를 찾아 URL, 순위, 검색 지표, 검색 의도, 예상 트래픽 맥락을 반환합니다.

Ranked Keywords API

도메인 또는 페이지 대상
순위 URL 매핑
순위 맥락
결과당 0.1 크레딧
준비됨
준비됨

매개변수를 입력하고 요청을 전송하세요. 작업 상태와 정규화된 결과가 여기에 표시됩니다.

README

SocQ 작성 · 업데이트

Ranked Keywords

순위 키워드는 일치하는 결과 URL을 통해 도메인, 서브도메인 또는 페이지와 연결된 검색어로, 그룹 순위, 절대 순위, 결과 페이지 순위와 함께 제공되는 수요, 난이도, 검색 의도, 트래픽 신호를 담고 있습니다. 이러한 검색어와 페이지의 관계는 노출 현황 목록 작성, 랜딩 페이지 매핑, 기회 검토, 대상별 스냅샷 비교에 활용할 수 있습니다.

Ranked Keywords API 주요 기능

  • 도메인, 서브도메인, 페이지 단위 범위올바른 형식의 웹 대상 하나를 도메인 전체, 서브도메인, 전체 페이지 URL 중 필요한 범위로 해석합니다.
  • 키워드와 URL의 관계반환된 키워드마다, 순위가 매겨진 검색 결과 요소가 가리키는 해당 URL을 짝지어 제공합니다.
  • 순위와 키워드 측정값제공되는 그룹 순위, 절대 순위, 결과 페이지 순위와 함께 검색량, CPC, 경쟁도, 난이도, 월별 추이, 검색 의도를 반환합니다.
  • 일치 요소 전체keyword_data와 ranked_serp_element를 extra 필드에 그대로 보존하므로, 결과 유형과 모델링된 트래픽, 정규화되지 않은 원본 세부 정보도 확인할 수 있습니다.

Ranked Keywords API 매개변수

매개변수필수설명
target필수도메인, 서브도메인 또는 페이지 대상으로, 필수 값입니다. 도메인은 https://와 www.를 빼고, 서브도메인은 프로토콜만 빼고 입력하며, 페이지 하나를 지정할 때는 전체 URL을 사용합니다.
location_code선택검색 시장을 나타내는 양수 코드입니다. 플레이그라운드의 기본값은 2840입니다.
location_name선택location_code 대신 쓸 수 있는 검색 시장 이름으로, 선택 값입니다. 입력하면 location_code보다 우선합니다.
language_code선택2~10자의 검색 언어 코드입니다. 플레이그라운드의 기본값은 en입니다.
language선택language_code 대신 쓸 수 있는 검색 언어 이름으로, 선택 값입니다. 입력하면 language_code보다 우선합니다.
results_limit선택요청할 순위 키워드 행의 최대 개수로, 1~1,000 범위입니다. 실제로는 더 적은 행이 반환될 수 있습니다.
offset선택요청한 결과 구간을 수집하기 전에 건너뛸 원본 행의 수로, 0부터 시작합니다.

Ranked Keywords API 사용 방법

범위를 올바르게 정한 대상 하나를 시장 설정, 제한된 결과 구간과 함께 제출하고, 완료된 비동기 작업에서 순위 키워드를 하나씩 읽습니다.

  1. target 하나, location_code, language_code, 1~1,000 범위의 results_limit, 0 이상의 offset을 정합니다.
  2. 페이로드를 /v1/seo/ranked-keywords로 POST하고, 반환된 task_id를 저장합니다.
  3. 작업이 성공하거나 실패할 때까지 /v1/tasks/{task_id}를 폴링합니다.
  4. data.results.items를 읽고, has_more가 true인 동안 반환된 next_cursor로 다음 결과를 요청합니다.
curl -X POST "https://api.socq.ai/v1/seo/ranked-keywords" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target":"microsoft.com","location_code":2840,"language_code":"en","results_limit":5}'

# Poll GET /v1/tasks/{task_id}
# Read data.results.items and follow next_cursor while has_more is true

Ranked Keywords API 추천 활용 사례

  • 오가닉 노출 현황 목록: 반환된 키워드 텍스트와 해당 URL을 활용해, 선택한 검색 시장에서 도메인이나 서브도메인이 어디에 노출되는지 정리합니다.
  • 랜딩 페이지 순위 매핑: 키워드, 도착 URL, rank 객체를 함께 살펴 반환된 순위마다 어떤 페이지가 연결되어 있는지 확인합니다.
  • 키워드 기회 검토: 순위를 검색량, CPC, 경쟁도, 난이도, 검색 의도 필드와 비교해 검토 대상 목록을 구성합니다.
  • 노출 스냅샷 비교: 반복 실행한 작업의 대상 입력, collected_at, 키워드, URL, 순위를 저장해 서로 다른 시점에 수집한 스냅샷을 비교합니다.

Ranked Keywords API 활용 팁

  • 의도한 범위로 해석되도록 도메인 대상에서는 https://와 www.를, 서브도메인 대상에서는 프로토콜을 제거하세요.
  • 페이지 단위 결과가 필요하면 전체 페이지 URL을 사용하세요. 프로토콜 없는 페이지 경로는 도메인 전체를 대상으로 해석될 수 있습니다.
  • 건너뛰려는 원본 행 수만큼 offset을 늘리고, 연속된 구간을 가져오는 동안에는 target, 시장, 언어, 제한 값을 고정하세요.
  • rank.page는 검색 결과 페이지 번호로 취급하세요. 원본 구간 이동에는 offset을, 저장된 SocQ 결과 페이지 이동에는 next_cursor를 각각 따로 사용합니다.
  • 먼저 정규화된 순위와 키워드 지표를 읽고, 모델링된 etv 등 정규화되지 않은 원본 필드는 extra.ranked_serp_element에서 확인하세요.
  • 원본 순서는 바뀔 수 있으므로, 반복 작업으로 과거 비교 데이터를 만들 때는 키워드, 일치 URL, 시장, 언어 기준으로 구간별 중복을 제거하세요.

Ranked Keywords API 외에 SEO의 다른 유형의 공개 데이터가 필요할 때 이 API를 사용하세요.

  • Google Organic SERP API — 검색어와 시장으로 실시간 Google 검색 결과 페이지 하나를 가져오며, 정규화된 도착 URL, 순위, 요소 유형, 전체 결과 상세를 포함합니다.
  • Keyword Difficulty API — 제출한 키워드 묶음의 오가닉 순위 난이도를 비교하며, 확인 가능한 각 키워드를 정규화된 점수와 함께 반환합니다.
  • Keyword Overview API — 제출한 키워드 묶음에 확인 가능한 수요, 유료 경쟁, 난이도, 월간 검색량, 검색 의도 맥락을 더해 보강합니다.
  • Keyword Search Volume API — 알고 있는 키워드의 검색량, CPC, 유료 경쟁, 월별 검색 추이를 측정합니다.
  • Keywords for Site API — 웹사이트 하나와 관련된 키워드를 생성하며, 확인 가능한 수요 측정값, 월별 추이, 시장 맥락, 전체 원본 행을 포함합니다.
  • Relevant Pages API — 도메인 하나의 색인된 페이지를 목록화하며, 오가닉 및 유료 순위 분포, 추정 트래픽, 예상 비용 맥락을 포함합니다.

다른 플랫폼 둘러보기

SEO 데이터를 지원되는 다른 소셜 플랫폼의 공개 데이터와 함께 활용하세요.

Ranked Keywords API — 자주 묻는 질문

Ranked Keywords API는 선택한 시장과 언어에서 도메인, 서브도메인 또는 페이지 하나와 연관된 검색어를 찾는 프로그래밍 인터페이스입니다. 일치하는 URL, 순위, 키워드 측정값, 월별 추이, 검색 의도, 원본 요소 전체를 반환합니다.

https://와 www.를 뺀 도메인, 프로토콜을 뺀 서브도메인, 또는 페이지 하나를 가리키는 전체 URL을 사용합니다. 프로토콜 없이 페이지 경로를 입력하면 범위가 도메인 전체로 넓어질 수 있습니다.

아니요. 순위는 선택한 검색 인덱스와 시장을 기준으로 한 값이며 모든 사용자에게 동일한 실시간 결과가 아니므로, 반복 수집한 스냅샷을 비교할 때는 collected_at을 활용하세요.

rank.page는 검색 결과 페이지 번호이고, offset은 원본 키워드 행을 건너뛰며, next_cursor는 SocQ 작업에 이미 저장된 결과를 페이지 단위로 넘깁니다. 세 값은 서로 대체할 수 없습니다.

아니요. etv는 extra.ranked_serp_element에 보존되는 모델링된 값이며, 대상 사이트의 비공개 트래픽이나 전환 데이터가 아닙니다.

반환된 순위 키워드 1개당 0.1 SocQ 크레딧이 차감됩니다. 결과가 비어 있으면 결과 요금이 부과되지 않으며, results_limit은 요청 전 예상치를 정할 뿐 최종 개수를 보장하지는 않습니다.