API JSON que retorna, com expansões, as sugestões de busca do Google, Bing, YouTube, Amazon, Rakuten Ichiba, Yahoo!, DuckDuckGo, Baidu, Yandex, Naver e Daum nos 20 idiomas do site. O japonês é expandido com o silabário kana (あ–ん), A–Z e 0–9; os demais idiomas, com um espaço mais as letras do próprio idioma, A–Z e 0–9. Você pode começar pelo plano gratuito (preços).
É necessária uma chave de API. Entre e gere a chave em “API”, no menu do usuário. Envie-a em todas as requisições.
Authorization: Bearer gsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Use a chave apenas no seu servidor. Se você a incluir no JavaScript do navegador, outras pessoas poderão usá-la.
Substitua {source} por um dos valores abaixo.
| source | Retorna |
|---|---|
google | Sugestões do Google |
bing | Sugestões do Bing |
youtube | Sugestões do YouTube |
amazon | Sugestões da Amazon (ja: Amazon.co.jp; outros idiomas: a principal loja desse idioma) |
rakuten | Sugestões do Rakuten Ichiba (Japão) |
yahoo | Sugestões da busca do Yahoo! |
duckduckgo | Sugestões do DuckDuckGo (lang=ja retorna sugestões para o Japão) |
baidu | Sugestões do Baidu (zh, zh-tw, ja, en) |
yandex | Sugestões do Yandex (ru, uk, tr) |
naver | Sugestões do Naver (ko) |
daum | Sugestões do Daum (ko) |
| Parâmetro | Descrição |
|---|---|
q (obrigatório) | Palavra-chave (1 a 60 caracteres). Caracteres de largura total e meia largura, maiúsculas e minúsculas e espaços são normalizados. |
lang | ja (padrão), en, ru, ko, zh e os demais códigos de idioma do site (20 no total). ja adiciona a expansão com kana (nihongo); os outros idiomas, um espaço mais suas próprias letras (native). en não tem nenhuma das duas. |
group | all (padrão) ou uma lista separada por vírgulas de itself,nihongo,native,alphabet,number. |
flat | Com 1, retorna um único array suggestions sem duplicatas. |
Buscar uma palavra-chave que ainda não está em cache leva algumas dezenas de segundos, por isso a API primeiro retorna 202 e a coloca na fila. Envie a mesma requisição de novo depois de retry_after_seconds; quando os dados estiverem prontos, você recebe 200 com os resultados. Os resultados ficam em cache por 7 dias. Depois que expiram, os dados antigos continuam sendo retornados com "stale": true enquanto são atualizados. O cache é separado para cada combinação de source, q e 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 (na fila)
{ "ok": true, "status": "queued", "source": "google", "queue_position": 3, "retry_after_seconds": 24, ... }
// 200 (pronto)
{ "ok": true, "status": "ready", "query": "ランニング", "source": "google", "fetched_at": "2026-09-19T01:02:03Z",
"stale": false, "count": 412, "suggestions": ["ランニング シューズ", "..."] }
GET /api/v1/usage — Uso da sua chave nos últimos 30 dias e limites do seu plano (requer autenticação)GET /api/v1/status — Tamanho da fila e status dos workers (sem autenticação)| Item | Limite |
|---|---|
| Requisições por minuto | 30 |
| Requisições por dia (UTC) | 1,000 |
| Palavras-chave novas (fora do cache) por dia | 20 Contadas separadamente para cada source. Palavras-chave que já estão em cache não contam. |
Quando um limite é excedido, a API retorna 429 com Retry-After. Todas as respostas incluem X-RateLimit-Limit / Remaining / Reset e X-Daily-Limit / X-Daily-Remaining.
| HTTP | code | Significado |
|---|---|---|
| 400 | invalid_query / invalid_lang / invalid_group | Parâmetro inválido (incluindo um source não oferecido para esse idioma) |
| 401 | invalid_api_key | Chave ausente ou inválida |
| 404 | not_found | source ou caminho inválido |
| 429 | rate_limited / daily_quota_exceeded / new_keyword_quota_exceeded | Limite excedido (veja Retry-After) |
| 502 | upstream_failed | Falha ao buscar os dados (tente de novo após uma hora) |
| 503 | queue_full | Serviço ocupado (veja Retry-After) |
Termos de serviço (English) · Política de privacidade (English)