Suggest API v1

API JSON que retorna els suggeriments de cerca (amb ampliació) de Google, Bing, YouTube, Amazon, eBay, Shopee, Rakuten Ichiba, Yahoo!, DuckDuckGo, Baidu, Yandex, Naver i Daum en les 50 llengües del lloc web. El japonès s'amplia amb el sil·labari kana (あ–ん), A–Z i 0–9, i les altres llengües amb un espai i les lletres pròpies de cada llengua, A–Z i 0–9. Pot començar amb el pla gratuït (preus).

Autenticació

Cal una clau d'API. Iniciï la sessió i generi una clau des de l'opció «API» del menú d'usuari. Inclogui-la en totes les sol·licituds.

Authorization: Bearer gsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Utilitzi la clau només des del seu servidor (si la inclou al JavaScript del navegador, altres persones la podran fer servir).

GET /api/v1/{source}/suggest

Substitueixi {source} per un dels valors següents.

source	Retorna
`google`	Suggeriments de Google
`bing`	Suggeriments de Bing
`youtube`	Suggeriments de YouTube
`amazon`	Suggeriments d'Amazon. El mercat es tria amb `lang` i `country` (Amazon.com, Amazon.co.uk, Amazon.de, Amazon.co.jp, etc.)
`ebay`	Suggeriments d'eBay. El lloc es tria amb `lang` i `country` (ebay.com, ebay.co.uk, ebay.de, ebay.fr, etc.; `en`, `de`, `fr`, `it`, `es`, `nl`, `pl`)
`shopee`	Suggeriments de Shopee. El lloc es tria amb `lang` i `country` (shopee.tw, shopee.sg, shopee.com.my, shopee.ph, shopee.co.id, shopee.vn, shopee.co.th, shopee.com.br, etc.; `zh-tw`, `en`, `ms`, `fil`, `id`, `vi`, `th`, `pt`)
`duckduckgo`	Suggeriments de DuckDuckGo (amb `lang=ja`, suggeriments per al Japó)
`baidu`	Suggeriments de Baidu (`zh`, `ja`, `en`)
`yandex`	Suggeriments de Yandex (`ru`, `tr`, `kk`, `uz`)
`naver`	Suggeriments de Naver (`ko`)
`daum`	Suggeriments de Daum (`ko`)
`yahoo`	Suggeriments de cerca de Yahoo! JAPAN (per al Japó) · `zh-tw`: Yahoo奇摩 (Taiwan)
`rakuten`	Suggeriments de Rakuten Ichiba (per al Japó)

Paràmetre	Descripció
`q` (obligatori)	Paraula clau (1–60 caràcters). Es normalitzen l'amplada completa/mitja, les majúscules/minúscules i els espais.
`lang`	`ja` (per defecte; es manté per als clients existents, però es recomana indicar-lo explícitament), `en`, `ru`, `ko`, `zh` i els altres codis de les 50 llengües del lloc. `ja` s'amplia amb el sil·labari kana (`nihongo`), i les altres llengües amb un espai i les seves lletres pròpies (`native`). `en` no té ampliació kana ni de lletres pròpies.
`country`	País / mercat (opcional, codi ISO 3166-1 de 2 lletres). `en`: us (per defecte), gb, ca, au, in, ie, nz, sg, za, ph; `es`: es, mx, ar, co, cl, pe, us; `pt`: br, pt; `fr`: fr, ca, be, ch; `de`: de, at, ch; `zh-tw`: tw, hk; i altres. S'aplica a Amazon (mercat), Bing, DuckDuckGo, Google i YouTube. Amazon, Bing i DuckDuckGo segueixen estrictament el país indicat. Google i YouTube també s'hi adapten, però el resultat encara pot reflectir des d'on s'envia la sol·licitud.
`group`	`all` (per defecte) o una llista separada per comes de `itself,nihongo,native,alphabet,number`.
`flat`	Amb `1` es retorna un únic vector `suggestions` sense duplicats.

Com funciona el flux asíncron

Obtenir una paraula clau que encara no és a la memòria cau triga unes quantes desenes de segons, per això l'API primer retorna 202 i la posa a la cua. Torni a enviar la mateixa sol·licitud passats retry_after_seconds; si les dades ja estan a punt, rebrà 200 amb les dades. Les dades obtingudes es desen a la memòria cau durant 7 dies. Un cop caducades, es retornen les dades antigues amb "stale": true mentre s'obtenen de nou. La memòria cau és independent per a cada combinació de source, q i lang.

curl -H "Authorization: Bearer $KEY" \
  "https://gstudio1.com/api/v1/google/suggest?q=running%20shoes&lang=en&country=us&flat=1"

curl -H "Authorization: Bearer $KEY" \
  "https://gstudio1.com/api/v1/amazon/suggest?q=running%20shoes&lang=en&country=gb&flat=1"

// 202 (a la cua)
{ "ok": true, "status": "queued", "source": "google", "lang": "en", "country": "us", "queue_position": 3, "retry_after_seconds": 24, ... }

// 200 (a punt)
{ "ok": true, "status": "ready", "query": "running shoes", "source": "google", "lang": "en", "country": "us", "fetched_at": "2026-10-24T01:02:03Z",
  "stale": false, "count": 268, "suggestions": ["running shoes for women", "..."] }

Altres endpoints

GET /api/v1/usage — Ús de la seva clau durant els últims 30 dies i límits del pla (cal autenticació)
GET /api/v1/status — Mida de la cua i estat dels workers (sense autenticació)

Límits (pla gratuït)

Element	Límit
Sol·licituds per minut	30
Sol·licituds per dia (UTC)	1,000
Paraules clau noves (no desades a la memòria cau) per dia	20 Es compten per separat per a cada source. Les paraules clau ja obtingudes no compten.

Si se supera un límit, l'API retorna 429 amb Retry-After. Totes les respostes inclouen X-RateLimit-Limit / Remaining / Reset i X-Daily-Limit / X-Daily-Remaining.

Errors

HTTP	code	Significat
400	invalid_query / invalid_lang / invalid_country / invalid_group / source_not_offered	Paràmetre no vàlid (inclòs un `source` que no s'ofereix per a aquella llengua)
401	invalid_api_key	Clau absent o no vàlida
404	not_found	`source` o ruta no vàlids
429	rate_limited / daily_quota_exceeded / new_keyword_quota_exceeded	Límit superat (vegi `Retry-After`)
502	upstream_failed	Error en l'obtenció (pot tornar-ho a provar d'aquí a una hora)
503	queue_full	Servei saturat (vegi `Retry-After`)

Contacte

Per a límits més alts, ús comercial o informes d'errors, escrigui directament al responsable (Yuki Nakazawa) per Telegram o per missatge directe a X. Responem en japonès i en anglès.

Abans d'utilitzar l'API

Els límits del pla gratuït poden canviar sense avís previ. Per als plans de pagament, consulti la pàgina de preus.
Les dades es basen en les respostes públiques de suggeriments de cada servei. No se'n garanteix l'exactitud ni la continuïtat (SLA).

Condicions del servei (English) · Política de privadesa (English)