Suggest API v1

Google, Bing, YouTube, Amazon, 라쿠텐 이치바, Yahoo!, DuckDuckGo, Baidu, Yandex, Naver, Daum의 서제스트(자동완성 검색어)를 확장까지 포함해 사이트의 20개 언어로 가져오는 JSON API입니다. 일본어는 가나(あ–ん), A–Z, 0–9로, 다른 언어는 스페이스와 각 언어의 문자, A–Z, 0–9로 확장합니다. 무료 요금제부터 이용할 수 있습니다(요금).

인증

API 키가 필요합니다. 로그인한 뒤 사용자 메뉴의 'API'에서 키를 발급받을 수 있습니다. 모든 요청에 키를 포함하세요.

Authorization: Bearer gsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

키는 서버 측에서만 사용하세요. 브라우저의 JavaScript에 넣으면 다른 사람이 키를 사용할 수 있습니다.

GET /api/v1/{source}/suggest

{source}에는 다음 중 하나를 지정합니다.

source	반환 내용
`google`	Google 서제스트
`bing`	Bing 서제스트
`youtube`	YouTube 서제스트
`amazon`	Amazon 서제스트 (`ja`는 Amazon.co.jp, 다른 언어는 해당 언어의 주요 마켓)
`rakuten`	라쿠텐 이치바 서제스트
`yahoo`	Yahoo! 검색 서제스트
`duckduckgo`	DuckDuckGo 서제스트 (`lang=ja`는 일본 대상 후보)
`baidu`	Baidu 서제스트 (`zh`, `zh-tw`, `ja`, `en`)
`yandex`	Yandex 서제스트 (`ru`, `uk`, `tr`)
`naver`	Naver 서제스트 (`ko`)
`daum`	Daum 서제스트 (`ko`)

파라미터	설명
`q` (필수)	키워드(1–60자). 전각/반각, 대소문자, 공백은 정규화됩니다.
`lang`	`ja`(기본값), `en`, `ru`, `ko`, `zh` 등 사이트의 20개 언어 코드. `ja`는 일본어 가나 확장(`nihongo`), 다른 언어는 스페이스와 각 언어의 문자로 확장(`native`)합니다. `en`에는 가나 확장도 고유 문자 확장도 없습니다.
`group`	`all`(기본값) 또는 `itself,nihongo,native,alphabet,number` 중에서 쉼표로 구분한 목록.
`flat`	`1`을 지정하면 중복을 제거한 하나의 `suggestions` 배열로 반환합니다.

비동기 처리 방식

아직 가져오지 않은 키워드는 수집에 수십 초가 걸리므로, 먼저 202를 반환하고 대기열에 넣습니다. retry_after_seconds초 후에 같은 요청을 다시 보내면, 수집이 끝난 경우 200과 함께 데이터가 반환됩니다. 수집된 데이터는 7일간 캐시되며, 만료된 뒤에도 다시 수집하는 동안에는 "stale": true와 함께 이전 데이터를 반환합니다. 캐시는 source, q, lang 조합마다 따로 관리됩니다.

curl -H "Authorization: Bearer $KEY" \
  "https://gstudio1.com/api/v1/google/suggest?q=%E3%83%A9%E3%83%B3%E3%83%8B%E3%83%B3%E3%82%B0&flat=1"

curl -H "Authorization: Bearer $KEY" \
  "https://gstudio1.com/api/v1/rakuten/suggest?q=%E3%83%A9%E3%83%B3%E3%83%8B%E3%83%B3%E3%82%B0&flat=1"

// 202 (대기열 등록)
{ "ok": true, "status": "queued", "source": "google", "queue_position": 3, "retry_after_seconds": 24, ... }

// 200 (수집 완료)
{ "ok": true, "status": "ready", "query": "ランニング", "source": "google", "fetched_at": "2026-09-19T01:02:03Z",
  "stale": false, "count": 412, "suggestions": ["ランニング シューズ", "..."] }

기타 엔드포인트

GET /api/v1/usage — 내 키의 최근 30일 사용량과 요금제 한도 (인증 필요)
GET /api/v1/status — 대기열 길이와 워커 가동 상태 (인증 불필요)

제한 (무료 요금제)

항목	한도
분당 요청 수	30
일일 요청 수 (UTC)	1,000
일일 신규(미캐시) 키워드 수	20 ※ source별로 집계되며, 이미 캐시된 키워드는 차감되지 않습니다

한도를 초과하면 429와 Retry-After를 반환합니다. 모든 응답에는 X-RateLimit-Limit / Remaining / Reset 및 X-Daily-Limit / X-Daily-Remaining 헤더가 포함됩니다.

오류

HTTP	code	의미
400	invalid_query / invalid_lang / invalid_group	잘못된 파라미터 (해당 언어에서 제공하지 않는 `source` 포함)
401	invalid_api_key	키가 없거나 유효하지 않음
404	not_found	잘못된 `source` 또는 경로
429	rate_limited / daily_quota_exceeded / new_keyword_quota_exceeded	한도 초과 (`Retry-After` 참조)
502	upstream_failed	수집 실패 (1시간 후 재시도 가능)
503	queue_full	혼잡 (`Retry-After` 참조)

이용 시 유의사항

무료 요금제의 제한 값은 예고 없이 변경될 수 있습니다. 유료 요금제는 요금 페이지를 참고하세요.
데이터는 각 서비스가 공개하는 서제스트 응답을 바탕으로 하며, 정확성과 지속성(SLA)은 보장하지 않습니다.