Suggest API v1

API JSON que devuelve, con ampliaciones, las sugerencias de búsqueda de Google, Bing, YouTube, Amazon, Rakuten Ichiba, Yahoo!, DuckDuckGo, Baidu, Yandex, Naver y Daum en los 20 idiomas del sitio. El japonés se amplía con el silabario kana (あ–ん), A–Z y 0–9; los demás idiomas, con un espacio más las letras propias del idioma, A–Z y 0–9. Puedes empezar con el plan gratuito (precios).

Autenticación

Se necesita una clave de API. Tras iniciar sesión, genera la clave en «API», dentro del menú de usuario. Inclúyela en todas las solicitudes.

Authorization: Bearer gsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Usa la clave solo desde tu servidor. Si la incluyes en el JavaScript del navegador, otras personas podrán usarla.

GET /api/v1/{source}/suggest

Sustituye {source} por uno de los siguientes valores.

source	Devuelve
`google`	Sugerencias de Google
`bing`	Sugerencias de Bing
`youtube`	Sugerencias de YouTube
`amazon`	Sugerencias de Amazon (`ja`: Amazon.co.jp; otros idiomas: la tienda principal de ese idioma)
`rakuten`	Sugerencias de Rakuten Ichiba (Japón)
`yahoo`	Sugerencias de búsqueda de Yahoo!
`duckduckgo`	Sugerencias de DuckDuckGo (`lang=ja` devuelve sugerencias para Japón)
`baidu`	Sugerencias de Baidu (`zh`, `zh-tw`, `ja`, `en`)
`yandex`	Sugerencias de Yandex (`ru`, `uk`, `tr`)
`naver`	Sugerencias de Naver (`ko`)
`daum`	Sugerencias de Daum (`ko`)

Parámetro	Descripción
`q` (obligatorio)	Palabra clave (de 1 a 60 caracteres). Se normalizan los caracteres de ancho completo y medio ancho, las mayúsculas y minúsculas, y los espacios.
`lang`	`ja` (predeterminado), `en`, `ru`, `ko`, `zh` y los demás códigos de idioma del sitio (20 en total). `ja` añade la ampliación con kana (`nihongo`); los demás idiomas, un espacio más sus propias letras (`native`). `en` no tiene ninguna de las dos.
`group`	`all` (predeterminado) o una lista separada por comas de `itself,nihongo,native,alphabet,number`.
`flat`	Con `1` se devuelve un único array `suggestions` sin duplicados.

Funcionamiento asíncrono

Obtener una palabra clave que aún no está en caché tarda unas decenas de segundos, así que la API responde primero con 202 y la pone en cola. Vuelve a enviar la misma solicitud pasados retry_after_seconds: si los datos ya están listos, recibirás 200 con los resultados. Los resultados se guardan en caché durante 7 días. Cuando caducan, se siguen devolviendo los datos antiguos con "stale": true mientras se actualizan. La caché es independiente para cada combinación de source, q y 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 (en cola)
{ "ok": true, "status": "queued", "source": "google", "queue_position": 3, "retry_after_seconds": 24, ... }

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

Otros endpoints

GET /api/v1/usage — Uso de tu clave en los últimos 30 días y límites de tu plan (requiere autenticación)
GET /api/v1/status — Longitud de la cola y estado de los workers (sin autenticación)

Límites (plan gratuito)

Concepto	Límite
Solicitudes por minuto	30
Solicitudes por día (UTC)	1,000
Palabras clave nuevas (sin caché) por día	20 Se cuentan por separado para cada source. Las palabras clave que ya están en caché no cuentan.

Si se supera un límite, la API devuelve 429 con Retry-After. Todas las respuestas incluyen X-RateLimit-Limit / Remaining / Reset y X-Daily-Limit / X-Daily-Remaining.

Errores

HTTP	code	Significado
400	invalid_query / invalid_lang / invalid_group	Parámetro no válido (incluido un `source` que no se ofrece para ese idioma)
401	invalid_api_key	Clave ausente o no válida
404	not_found	`source` o ruta no válidos
429	rate_limited / daily_quota_exceeded / new_keyword_quota_exceeded	Límite superado (consulta `Retry-After`)
502	upstream_failed	Error al obtener los datos (puedes reintentarlo al cabo de una hora)
503	queue_full	Servicio saturado (consulta `Retry-After`)

Antes de usar la API

Los límites del plan gratuito pueden cambiar sin previo aviso. Para los planes de pago, consulta la página de precios.
Los datos se basan en las respuestas públicas de sugerencias de cada servicio. No se garantizan su exactitud ni su continuidad (SLA).

Términos del servicio (English) · Política de privacidad (English)