seo/
keyword-suggestions

선택한 검색 시장에서 시드 검색어 하나를 롱테일 키워드로 확장하고, 일치한 키워드와 제공 가능한 수요 지표, 월별 추이, 원본 행 전체를 반환합니다.

Keyword Suggestions API

시드 구문 매칭
롱테일 키워드
오프셋 구간
결과당 0.1 크레딧
준비됨
준비됨

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

README

SocQ 작성 · 업데이트

Keyword Suggestions

키워드 제안은 시드 단어나 구문의 앞, 뒤, 또는 중간에 다른 말이 붙은 롱테일 검색어이며, 레코드에는 수요, 비용, 경쟁도, 월별 추이, 검색 의도 신호가 포함될 수 있습니다. 이렇게 일치한 검색어와 측정값은 검색어 확장, 콘텐츠 브리프 리서치, 유료 검색 분석, 표현 변형의 통제된 비교에 활용할 수 있습니다.

Keyword Suggestions API 주요 기능

  • 전문 일치 시드 확장제출한 시드 단어를 유지하면서 구문의 앞, 뒤, 중간에 말이 붙거나 단어 순서가 다른 검색어를 반환합니다.
  • 키워드 측정 객체확인 가능한 검색량, CPC, 유료 경쟁도, 월별 추이, 난이도 상세 정보를 각 레코드의 원본 데이터 안에 보존합니다.
  • 검색 의도 맥락일치한 키워드마다 확인 가능한 주요·보조 검색 의도 정보를 제공하며, 이를 순위 권장 사항으로 취급하지는 않습니다.
  • 통제 가능한 결과 구간1에서 1,000 사이의 결과 수 상한과, 이후의 원본 구간을 가져오기 위한 0부터 시작하는 행 오프셋을 받습니다.

Keyword Suggestions API 매개변수

매개변수필수설명
query필수비어 있지 않아야 하는 필수 시드 키워드 또는 구문입니다. 작업 하나에는 검색어 하나만 사용할 수 있습니다.
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부터 시작합니다.

Keyword Suggestions API 사용 방법

시드 검색어 하나를 시장 설정과 한정된 결과 구간과 함께 제출하고, 완료된 비동기 작업에서 제안을 하나씩 읽습니다.

  1. 비어 있지 않은 query 하나, location_code, language_code, 1에서 1,000 사이의 results_limit, 0 이상의 offset을 정합니다.
  2. 페이로드를 /v1/seo/keyword-suggestions로 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-suggestions" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"keyword research","location_code":2840,"language_code":"en","results_limit":100}'

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

Keyword Suggestions API 추천 활용 사례

  • 롱테일 검색어 확장: 시드 구문 하나와 반환된 키워드 텍스트를 활용해 원래 단어를 유지한 더 긴 검색어 변형을 모읍니다.
  • 콘텐츠 브리프 후보 리서치: 일치한 검색어를 제공 가능한 검색량, 월별 추이, 난이도, 검색 의도 필드와 결합해 검토할 수 있는 키워드 세트를 구성합니다.
  • 유료 검색 키워드 비교: 후보를 기획 워크플로로 넘기기 전에 표현 변형 간 제공 가능한 CPC와 유료 경쟁도 측정값을 비교합니다.

Keyword Suggestions API 활용 팁

  • 촘촘하게 일치하는 롱테일 변형이 필요하면 구체적인 시드 구문을 사용하고, 시드 단어를 포함하지 않아도 된다면 의미 기반 키워드 엔드포인트를 선택하세요.
  • offset은 페이지 번호가 아니라 행 수로 취급하고, 건너뛰려는 원본 구간의 크기만큼 늘려 가세요.
  • 다른 조건이 같은 요청이라도 이후 원본 정렬 순서가 달라질 수 있으므로 query, location_code, language_code, results_limit, offset을 함께 기록하세요.
  • keyword와 search_intent는 정규화된 필드에서 먼저 읽고, 승격되지 않은 측정 객체는 extra.keyword_info와 extra.keyword_properties에서 확인하세요.
  • 반복된 구간은 키워드에 시장과 언어를 더한 값으로 중복을 제거하고, 선택적인 지표나 중첩 객체는 모두 없을 수 있다고 가정하세요.

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

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

다른 플랫폼 둘러보기

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

Keyword Suggestions API — 자주 묻는 질문

Keyword Suggestions API는 시드 검색어 하나와 시장 코드, 언어 코드로 롱테일 검색어를 찾는 프로그래밍 인터페이스입니다. 일치한 키워드와 제공 가능한 수요·경쟁 상세 정보, 월별 추이, 검색 의도 맥락, 원본 행 전체를 반환합니다.

제안에는 제출한 시드 단어가 포함되며 그 앞, 뒤, 중간에 말이 붙지만 단어 순서는 다를 수 있습니다. 넓은 의미의 대안이 아니라 전문 일치 확장에 이 엔드포인트를 사용하세요.

results_limit은 1에서 1,000 사이의 상한이고 offset은 건너뛸 앞쪽 원본 행의 수입니다. offset은 페이지 번호가 아니며 원본 정렬 순서는 시간이 지나면서 달라질 수 있습니다.

안정적인 keyword와 제공 가능한 검색 의도 필드는 정규화되고, 직접 측정한 검색 지표와 키워드 속성은 extra.keyword_info와 extra.keyword_properties에 남을 수 있습니다. 클라이언트는 선택적인 값을 모두 null일 수 있는 값으로 다뤄야 합니다.

반환된 제안 1건마다 0.1 SocQ 크레딧이 차감됩니다. 결과가 비어 있으면 결과 요금이 청구되지 않으며, 요청 전 예상치는 results_limit을 기준으로 하므로 최종 개수를 보장하는 값이 아닙니다.