Keyword Difficulty
키워드 난이도 점수는 검색어로 자연 검색 상위에 노출되기 위한 상대적 경쟁 정도를 추정해 나타내며, 값이 높을수록 어렵다는 뜻입니다. 이러한 키워드 단위의 신호는 우선순위 정하기, 리서치 그룹 분류, 준비한 키워드 목록 간 비교에 활용할 수 있습니다.
Keyword Difficulty API 주요 기능
- 키워드 일괄 입력선택한 시장과 언어 조건을 일괄 요청 전체에 똑같이 적용해, 작업 하나에서 비어 있지 않은 키워드 1~1,000개를 평가합니다.
- 정규화된 난이도 지표확인 가능한 키워드마다 metrics.keyword_difficulty를 반환하며, 직접 비교할 수 있도록 보통 0~100 척도로 표현됩니다.
- 원본 정보 전체 유지반환된 행 전체를 extra에 보존하므로 클라이언트가 추가 원본 필드를 확인할 수 있으며, 이 필드를 안정적인 정규화 스키마로 취급해서는 안 됩니다.
Keyword Difficulty API 매개변수
| 매개변수 | 필수 | 설명 |
|---|---|---|
keywords | 필수 | 비어 있지 않은 키워드 1~1,000개의 목록으로, 필수 값입니다. 항목당 최대 80자까지 사용할 수 있습니다. |
location_code | 선택 | 양의 정수인 검색 시장 코드입니다. 플레이그라운드의 기본값은 미국을 뜻하는 2840입니다. |
location_name | 선택 | location_code 대신 쓸 수 있는 검색 시장 이름으로, 선택 값입니다. 입력하면 location_code보다 우선합니다. |
language_code | 선택 | 일괄 요청 전체에 적용되는 길이 2~10자의 검색 언어 코드입니다. 플레이그라운드의 기본값은 en입니다. |
language | 선택 | language_code 대신 쓸 수 있는 검색 언어 이름으로, 선택 값입니다. 입력하면 language_code보다 우선합니다. |
results_limit | 선택 | 1에서 2,000 사이의 결과 수 제한으로, 선택 값입니다. |
Keyword Difficulty API 사용 방법
개수가 정해진 키워드 목록을 코드 기반 시장 설정과 함께 제출하고, 완료된 비동기 작업에서 확인 가능한 정규화 점수를 읽습니다.
- 각각 80자 이하인 비어 있지 않은 키워드 1~1,000개를 준비합니다.
- keywords를 location_code, language_code와 함께 /v1/seo/keyword-difficulty로 POST하고, 반환된 task_id를 저장합니다.
- 작업이 성공하거나 실패를 반환할 때까지 /v1/tasks/{task_id}를 폴링합니다.
- data.results.items를 읽고, has_more가 true인 동안 next_cursor를 따라갑니다.
curl -X POST "https://api.socq.ai/v1/seo/keyword-difficulty" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"keywords":["keyword research","seo tools"],"location_code":2840,"language_code":"en"}'
# Poll GET /v1/tasks/{task_id}
# Read data.results.items and follow next_cursor while has_more is trueKeyword Difficulty API 추천 활용 사례
- 키워드 목록 우선순위 정하기: 준비한 키워드 집합 전체에서 metrics.keyword_difficulty를 비교해, 콘텐츠 기획이나 리서치 분류에 경쟁 정도라는 신호를 더합니다.
- 난이도 구간별 분류: 반환된 점수를 내부 기준의 구간으로 묶어 난이도가 낮은 키워드와 높은 키워드의 리서치 대기열을 나눠 관리합니다.
- 시장별 비교: location_code와 language_code 값을 통제한 상태로 같은 키워드 목록을 실행해, 검색 환경에 따른 추정 난이도를 비교합니다.
Keyword Difficulty API 활용 팁
- 같은 키워드가 반복되어 입력 기준 요금이 중복으로 발생하지 않도록, 제출 전에 키워드의 중복을 제거하세요.
- 하나의 리서치 세트 안에서 점수를 비교할 때는 location_code와 language_code를 바꾸지 마세요.
- 이 일괄 요청은 반환 결과 수 제한이 아니라 keywords 배열로 제어되므로 results_limit은 생략하세요.
- 점수를 계산할 수 없는 키워드는 반환 레코드에서 빠질 수 있으므로, 배열 순서가 아니라 키워드로 결과를 대응시키세요.
- 점수 구간을 만들 때는 숫자 점수 0과 keyword_difficulty 값이 없는 경우를 구분하세요.
관련 API
Keyword Difficulty API 외에 SEO의 다른 유형의 공개 데이터가 필요할 때 이 API를 사용하세요.
- Google Organic SERP API — 검색어와 시장으로 실시간 Google 검색 결과 페이지 하나를 가져오며, 정규화된 도착 URL, 순위, 요소 유형, 전체 결과 상세를 포함합니다.
- Keyword Overview API — 제출한 키워드 묶음에 확인 가능한 수요, 유료 경쟁, 난이도, 월간 검색량, 검색 의도 맥락을 더해 보강합니다.
- Keyword Search Volume API — 알고 있는 키워드의 검색량, CPC, 유료 경쟁, 월별 검색 추이를 측정합니다.
- Keywords for Site API — 웹사이트 하나와 관련된 키워드를 생성하며, 확인 가능한 수요 측정값, 월별 추이, 시장 맥락, 전체 원본 행을 포함합니다.
- Keyword Suggestions API — 시드 검색어 하나를 일치하는 롱테일 키워드로 확장하며, 확인 가능한 수요 측정값, 월별 추이, 검색 의도 맥락, 전체 원본 행을 포함합니다.
- Search Intent API — 제출한 키워드 묶음의 주요 및 보조 검색 의도를 분류하며, 원본 확률값과 전체 레코드를 유지합니다.
- Ranked Keywords API
- Related Keywords API
- Relevant Pages 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