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 사용 방법
범위를 올바르게 정한 대상 하나를 시장 설정, 제한된 결과 구간과 함께 제출하고, 완료된 비동기 작업에서 순위 키워드를 하나씩 읽습니다.
- target 하나, location_code, language_code, 1~1,000 범위의 results_limit, 0 이상의 offset을 정합니다.
- 페이로드를 /v1/seo/ranked-keywords로 POST하고, 반환된 task_id를 저장합니다.
- 작업이 성공하거나 실패할 때까지 /v1/tasks/{task_id}를 폴링합니다.
- 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 trueRanked 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, 시장, 언어 기준으로 구간별 중복을 제거하세요.
관련 API
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 — 도메인 하나의 색인된 페이지를 목록화하며, 오가닉 및 유료 순위 분포, 추정 트래픽, 예상 비용 맥락을 포함합니다.
- Keyword Suggestions API
- Related Keywords API
- Search Intent API
- Backlinks Summary API
- Backlinks API
- Referring Domains API
- Backlink Competitors API
- Domain Overview API
- Competitor Domains API
- Traffic Estimate API
- Domain Technologies API
- Whois Lookup API
- Google News API
- Google Images API
- Bing Search API
- YouTube Rank Tracker API
- Google Autocomplete API