seo/
keyword-difficulty

한 시장에서 최대 1,000개 키워드의 자연 검색 순위 난이도를 비교하고, 확인 가능한 키워드와 0~100 점수를 정규화된 레코드로 반환합니다.

Keyword Difficulty API

최대 1,000개 키워드
0~100 난이도 점수
시장별 비교
키워드당 0.1 크레딧
준비됨
준비됨

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

README

SocQ 작성 · 업데이트

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 사용 방법

개수가 정해진 키워드 목록을 코드 기반 시장 설정과 함께 제출하고, 완료된 비동기 작업에서 확인 가능한 정규화 점수를 읽습니다.

  1. 각각 80자 이하인 비어 있지 않은 키워드 1~1,000개를 준비합니다.
  2. keywords를 location_code, language_code와 함께 /v1/seo/keyword-difficulty로 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/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 true

Keyword Difficulty API 추천 활용 사례

  • 키워드 목록 우선순위 정하기: 준비한 키워드 집합 전체에서 metrics.keyword_difficulty를 비교해, 콘텐츠 기획이나 리서치 분류에 경쟁 정도라는 신호를 더합니다.
  • 난이도 구간별 분류: 반환된 점수를 내부 기준의 구간으로 묶어 난이도가 낮은 키워드와 높은 키워드의 리서치 대기열을 나눠 관리합니다.
  • 시장별 비교: location_code와 language_code 값을 통제한 상태로 같은 키워드 목록을 실행해, 검색 환경에 따른 추정 난이도를 비교합니다.

Keyword Difficulty API 활용 팁

  • 같은 키워드가 반복되어 입력 기준 요금이 중복으로 발생하지 않도록, 제출 전에 키워드의 중복을 제거하세요.
  • 하나의 리서치 세트 안에서 점수를 비교할 때는 location_code와 language_code를 바꾸지 마세요.
  • 이 일괄 요청은 반환 결과 수 제한이 아니라 keywords 배열로 제어되므로 results_limit은 생략하세요.
  • 점수를 계산할 수 없는 키워드는 반환 레코드에서 빠질 수 있으므로, 배열 순서가 아니라 키워드로 결과를 대응시키세요.
  • 점수 구간을 만들 때는 숫자 점수 0과 keyword_difficulty 값이 없는 경우를 구분하세요.

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 — 제출한 키워드 묶음의 주요 및 보조 검색 의도를 분류하며, 원본 확률값과 전체 레코드를 유지합니다.

다른 플랫폼 둘러보기

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

Keyword Difficulty API — 자주 묻는 질문

Keyword Difficulty API는 한 검색 시장에서 제출한 키워드 1~1,000개의 자연 검색 순위 난이도를 비교하는 프로그래밍 인터페이스입니다. 확인 가능한 키워드마다 정규화된 0~100 난이도 점수와 원본 행 전체를 반환합니다.

작업 하나는 각각 80자 이하인 비어 있지 않은 키워드 문자열 1~1,000개를 받습니다. 일괄 요청의 크기는 keywords 배열이 정합니다.

반드시 그렇지는 않습니다. 점수를 계산할 수 없으면 키워드가 빠지거나 난이도 지표가 없을 수 있으므로, 입력 하나당 반환 행이 하나라고 가정하지 마세요.

아니요. 이 점수는 선택한 시장에서 자연 검색 순위 난이도를 비교하기 위한 추정치이며, 순위 확률이나 트래픽 예측, 사이트별 권장 사항이 아닙니다.

제출한 키워드 1개마다 0.1 SocQ 크레딧이 차감되며, 결과 행이 없는 키워드도 포함됩니다. 따라서 키워드 두 개를 보내는 플레이그라운드 요청의 예상 비용은 0.2 크레딧입니다.