Suggest API v1

JSON API, které vrací návrhy z našeptávačů (včetně rozšíření) Googlu, Bingu, YouTube, Amazonu, eBay, Shopee, Rakuten Ichiba, Yahoo!, DuckDuckGo, Baidu, Yandexu, Naveru a Daumu v 50 jazycích webu. Japonštinu rozšiřuje o slabičné písmo kana (あ–ん), A–Z a 0–9, ostatní jazyky o mezeru a vlastní písmena daného jazyka (v češtině např. á č ď é í ó ř š ť ú ž), A–Z a 0–9. Začít můžete s tarifem zdarma (ceník).

Ověření

Je nutný API klíč. Přihlaste se a vygenerujte si klíč v uživatelském menu v položce „API“. Posílejte ho s každým požadavkem.

Authorization: Bearer gsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Klíč používejte jen na straně serveru. Pokud ho vložíte do JavaScriptu v prohlížeči, mohou ho zneužít jiní.

GET /api/v1/{source}/suggest

Za {source} dosaďte jednu z následujících hodnot.

source	Vrací
`google`	Návrhy z našeptávače Google
`bing`	Návrhy z našeptávače Bing
`youtube`	Návrhy z našeptávače YouTube
`amazon`	Návrhy z našeptávače Amazon z tržiště zvoleného pomocí `lang` a `country` (Amazon.com, Amazon.co.uk, Amazon.de, Amazon.co.jp a další)
`ebay`	Návrhy z eBay z webu zvoleného pomocí `lang` a `country` (ebay.com, ebay.co.uk, ebay.de, ebay.fr a další; `en`, `de`, `fr`, `it`, `es`, `nl`, `pl`)
`shopee`	Návrhy ze Shopee z webu zvoleného pomocí `lang` a `country` (shopee.tw, shopee.sg, shopee.com.my, shopee.ph, shopee.co.id, shopee.vn, shopee.co.th, shopee.com.br a další; `zh-tw`, `en`, `ms`, `fil`, `id`, `vi`, `th`, `pt`)
`duckduckgo`	Návrhy z našeptávače DuckDuckGo (`lang=ja` vrací návrhy pro Japonsko)
`baidu`	Návrhy z našeptávače Baidu (`zh`, `ja`, `en`)
`yandex`	Návrhy z našeptávače Yandex (`ru`, `tr`, `kk`, `uz`)
`naver`	Návrhy z našeptávače Naver (`ko`)
`daum`	Návrhy z našeptávače Daum (`ko`)
`yahoo`	Návrhy vyhledávání Yahoo! JAPAN (jen Japonsko) · `zh-tw`: Yahoo奇摩 (Yahoo! Tchaj-wan)
`rakuten`	Návrhy z Rakuten Ichiba (jen Japonsko)

Parametr	Popis
`q` (povinný)	Klíčové slovo (1–60 znaků). Znaky plné a poloviční šířky, velikost písmen a mezery se normalizují.
`lang`	`ja` (výchozí; kvůli stávajícím uživatelům se nemění, doporučujeme ho ale uvádět výslovně), `en`, `ru`, `ko`, `zh` a další kódy jazyků webu (celkem 50). `ja` přidává rozšíření o kanu (`nihongo`), ostatní jazyky mezeru a vlastní písmena (`native`). `en` nemá ani jedno.
`country`	Země / trh (nepovinné, ISO 3166-1 alpha-2). `en`: us (výchozí), 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 další. Platí pro Amazon (tržiště), Bing, DuckDuckGo, Google a YouTube. Amazon, Bing a DuckDuckGo se zemí řídí přesně; Google a YouTube se jí také přizpůsobují, ale výsledky může dál ovlivňovat oblast, odkud je požadavek odeslán.
`group`	`all` (výchozí) nebo čárkami oddělený seznam z `itself,nihongo,native,alphabet,number`.
`flat`	`1` vrátí jediné pole `suggestions` bez duplicit.

Jak funguje asynchronní zpracování

Stažení klíčového slova, které ještě není v mezipaměti, trvá desítky sekund, proto API nejprve vrátí 202 a zařadí ho do fronty. Po retry_after_seconds pošlete stejný požadavek znovu; jakmile jsou data připravena, dostanete 200 s výsledky. Stažená data se ukládají do mezipaměti na 7 dní. Po vypršení se během obnovy vracejí stará data s "stale": true. Mezipaměť je oddělená pro každou kombinaci 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 (ve frontě)
{ "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", "..."] }

Další endpointy

GET /api/v1/usage — Využití vašeho klíče za posledních 30 dní a limity tarifu (vyžaduje ověření)
GET /api/v1/status — Délka fronty a stav workerů (bez ověření)

Limity (tarif zdarma)

Položka	Limit
Požadavky za minutu	30
Požadavky za den (UTC)	1,000
Nová klíčová slova (mimo mezipaměť) za den	20 Počítá se zvlášť pro každý source. Klíčová slova, která už jsou stažená, se nezapočítávají.

Při překročení limitu vrací API 429 s hlavičkou Retry-After. Každá odpověď 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ý parametr (včetně `source`, který pro daný jazyk není k dispozici)
401	invalid_api_key	Chybějící nebo neplatný klíč
404	not_found	Neplatný `source` nebo cesta
429	rate_limited / daily_quota_exceeded / new_keyword_quota_exceeded	Překročen limit (viz `Retry-After`)
502	upstream_failed	Stažení selhalo (opakovat lze po hodině)
503	queue_full	Přetížení (viz `Retry-After`)

Kontakt

Kvůli vyšším limitům, komerčnímu využití nebo hlášení chyb napište přímo provozovateli (Yuki Nakazawa) na Telegramu nebo do zpráv na X. Odpovídá anglicky nebo japonsky.

Než začnete API používat

Limity tarifu zdarma se mohou změnit bez předchozího upozornění. Placené tarify najdete na stránce s ceníkem.
Data vycházejí z veřejných odpovědí našeptávačů jednotlivých služeb. Za jejich přesnost a dostupnost (SLA) neručíme.

Podmínky používání (anglicky) · Zásady ochrany osobních údajů (anglicky)