Suggest API v1

JSON API, ktoré vracia návrhy z našepkávačov (vrátane rozšírenia) Googlu, Bingu, YouTube, Amazonu, eBay, Shopee, Rakuten Ichiba, Yahoo!, DuckDuckGo, Baidu, Yandexu, Naveru a Daumu v 50 jazykoch webu. Japončinu rozširuje o slabičné písmo kana (あ–ん), A–Z a 0–9, ostatné jazyky o medzeru a vlastné písmená daného jazyka (v slovenčine napr. á č ď é í ľ ó ô š ť ú ž), A–Z a 0–9. Začať môžete s tarifom zadarmo (cenník).

Overenie

Je potrebný API kľúč. Prihláste sa a vygenerujte si kľúč v používateľskom menu v položke „API“. Posielajte ho s každou požiadavkou.

Authorization: Bearer gsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Kľúč používajte len na strane servera. Ak ho vložíte do JavaScriptu v prehliadači, môžu ho zneužiť iní.

GET /api/v1/{source}/suggest

Za {source} dosaďte jednu z nasledujúcich hodnôt.

source	Vracia
`google`	Návrhy z našepkávača Google
`bing`	Návrhy z našepkávača Bing
`youtube`	Návrhy z našepkávača YouTube
`amazon`	Návrhy z našepkávača Amazon z trhoviska zvoleného pomocou `lang` a `country` (Amazon.com, Amazon.co.uk, Amazon.de, Amazon.co.jp a ďalšie)
`ebay`	Návrhy z eBay z webu zvoleného pomocou `lang` a `country` (ebay.com, ebay.co.uk, ebay.de, ebay.fr a ďalšie; `en`, `de`, `fr`, `it`, `es`, `nl`, `pl`)
`shopee`	Návrhy zo Shopee z webu zvoleného pomocou `lang` a `country` (shopee.tw, shopee.sg, shopee.com.my, shopee.ph, shopee.co.id, shopee.vn, shopee.co.th, shopee.com.br a ďalšie; `zh-tw`, `en`, `ms`, `fil`, `id`, `vi`, `th`, `pt`)
`duckduckgo`	Návrhy z našepkávača DuckDuckGo (`lang=ja` vracia návrhy pre Japonsko)
`baidu`	Návrhy z našepkávača Baidu (`zh`, `ja`, `en`)
`yandex`	Návrhy z našepkávača Yandex (`ru`, `tr`, `kk`, `uz`)
`naver`	Návrhy z našepkávača Naver (`ko`)
`daum`	Návrhy z našepkávača Daum (`ko`)
`yahoo`	Návrhy vyhľadávania Yahoo! JAPAN (len Japonsko) · `zh-tw`: Yahoo奇摩 (Yahoo! Taiwan)
`rakuten`	Návrhy z Rakuten Ichiba (len Japonsko)

Parameter	Popis
`q` (povinný)	Kľúčové slovo (1–60 znakov). Znaky plnej a polovičnej šírky, veľkosť písmen a medzery sa normalizujú.
`lang`	`ja` (predvolené; kvôli existujúcim používateľom sa nemení, odporúčame ho však uvádzať výslovne), `en`, `ru`, `ko`, `zh` a ďalšie kódy jazykov webu (spolu 50). `ja` pridáva rozšírenie o kanu (`nihongo`), ostatné jazyky medzeru a vlastné písmená (`native`). `en` nemá ani jedno.
`country`	Krajina / trh (nepovinné, ISO 3166-1 alpha-2). `en`: us (predvolené), 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 a ďalšie. Platí pre Amazon (trhovisko), Bing, DuckDuckGo, Google a YouTube. Amazon, Bing a DuckDuckGo sa krajinou riadia presne; Google a YouTube sa jej tiež prispôsobujú, ale výsledky môže naďalej ovplyvňovať oblasť, odkiaľ je požiadavka odoslaná.
`group`	`all` (predvolené) alebo čiarkami oddelený zoznam z `itself,nihongo,native,alphabet,number`.
`flat`	`1` vráti jediné pole `suggestions` bez duplicít.

Ako funguje asynchrónne spracovanie

Stiahnutie kľúčového slova, ktoré ešte nie je vo vyrovnávacej pamäti, trvá desiatky sekúnd, preto API najprv vráti 202 a zaradí ho do radu. Po retry_after_seconds pošlite rovnakú požiadavku znova; keď sú dáta pripravené, dostanete 200 s výsledkami. Stiahnuté dáta sa ukladajú do vyrovnávacej pamäte na 7 dní. Po vypršaní sa počas obnovy vracajú staré dáta s "stale": true. Vyrovnávacia pamäť je oddelená pre každú kombináciu source, q a 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 (v rade)
{ "ok": true, "status": "queued", "source": "google", "lang": "en", "country": "us", "queue_position": 3, "retry_after_seconds": 24, ... }

// 200 (hotovo)
{ "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", "..."] }

Ďalšie endpointy

GET /api/v1/usage — Využitie vášho kľúča za posledných 30 dní a limity tarifu (vyžaduje overenie)
GET /api/v1/status — Dĺžka radu a stav workerov (bez overenia)

Limity (tarif zadarmo)

Položka	Limit
Požiadavky za minútu	30
Požiadavky za deň (UTC)	1,000
Nové kľúčové slová (mimo vyrovnávacej pamäte) za deň	20 Počíta sa osobitne pre každý source. Kľúčové slová, ktoré sú už stiahnuté, sa nezapočítavajú.

Pri prekročení limitu vracia API 429 s hlavičkou Retry-After. Každá odpoveď obsahuje X-RateLimit-Limit / Remaining / Reset a X-Daily-Limit / X-Daily-Remaining.

Chyby

HTTP	code	Význam
400	invalid_query / invalid_lang / invalid_country / invalid_group / source_not_offered	Neplatný parameter (vrátane `source`, ktorý pre daný jazyk nie je k dispozícii)
401	invalid_api_key	Chýbajúci alebo neplatný kľúč
404	not_found	Neplatný `source` alebo cesta
429	rate_limited / daily_quota_exceeded / new_keyword_quota_exceeded	Prekročený limit (pozri `Retry-After`)
502	upstream_failed	Stiahnutie zlyhalo (opakovať možno po hodine)
503	queue_full	Preťaženie (pozri `Retry-After`)

Kontakt

Ak potrebujete vyššie limity, komerčné využitie alebo chcete nahlásiť chybu, napíšte priamo prevádzkovateľovi (Yuki Nakazawa) na Telegrame alebo do správ na X. Odpovedá po anglicky alebo po japonsky.

Skôr než začnete API používať

Limity tarifu zadarmo sa môžu zmeniť bez predchádzajúceho upozornenia. Platené tarify nájdete na stránke s cenníkom.
Dáta vychádzajú z verejných odpovedí našepkávačov jednotlivých služieb. Za ich presnosť a dostupnosť (SLA) neručíme.

Podmienky používania (po anglicky) · Zásady ochrany osobných údajov (po anglicky)