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 사용 방법
시드 검색어 하나를 시장 설정과 한정된 결과 구간과 함께 제출하고, 완료된 비동기 작업에서 제안을 하나씩 읽습니다.
- 비어 있지 않은 query 하나, location_code, language_code, 1에서 1,000 사이의 results_limit, 0 이상의 offset을 정합니다.
- 페이로드를 /v1/seo/keyword-suggestions로 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-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 trueKeyword Suggestions API 추천 활용 사례
- 롱테일 검색어 확장: 시드 구문 하나와 반환된 키워드 텍스트를 활용해 원래 단어를 유지한 더 긴 검색어 변형을 모읍니다.
- 콘텐츠 브리프 후보 리서치: 일치한 검색어를 제공 가능한 검색량, 월별 추이, 난이도, 검색 의도 필드와 결합해 검토할 수 있는 키워드 세트를 구성합니다.
- 유료 검색 키워드 비교: 후보를 기획 워크플로로 넘기기 전에 표현 변형 간 제공 가능한 CPC와 유료 경쟁도 측정값을 비교합니다.
Keyword Suggestions API 활용 팁
- 촘촘하게 일치하는 롱테일 변형이 필요하면 구체적인 시드 구문을 사용하고, 시드 단어를 포함하지 않아도 된다면 의미 기반 키워드 엔드포인트를 선택하세요.
- offset은 페이지 번호가 아니라 행 수로 취급하고, 건너뛰려는 원본 구간의 크기만큼 늘려 가세요.
- 다른 조건이 같은 요청이라도 이후 원본 정렬 순서가 달라질 수 있으므로 query, location_code, language_code, results_limit, offset을 함께 기록하세요.
- keyword와 search_intent는 정규화된 필드에서 먼저 읽고, 승격되지 않은 측정 객체는 extra.keyword_info와 extra.keyword_properties에서 확인하세요.
- 반복된 구간은 키워드에 시장과 언어를 더한 값으로 중복을 제거하고, 선택적인 지표나 중첩 객체는 모두 없을 수 있다고 가정하세요.
관련 API
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 — 시드 검색어 하나에서 연관 검색 경로를 따라가며, 깊이 설정, 확인 가능한 키워드 측정값, 검색 의도 맥락, 전체 원본 행을 포함합니다.
- Ranked Keywords API
- Relevant Pages 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