JSON API, amely a Google, a Bing, a YouTube, az Amazon, az eBay, a Shopee, a Rakuten Ichiba, a Yahoo!, a DuckDuckGo, a Baidu, a Yandex, a Naver és a Daum keresési javaslatait adja vissza bővítéssel együtt, a webhely 50 nyelvén. A japán nyelvet kana szótagokkal (あ–ん), A–Z és 0–9 karakterekkel bővíti, a többi nyelvet szóközzel, az adott nyelv saját betűivel (magyarul például á é í ó ö ő ú ü ű), valamint A–Z és 0–9 karakterekkel. Az ingyenes csomaggal is kezdheti (árak).
API-kulcs szükséges. Jelentkezzen be, majd a felhasználói menü „API” pontjában hozzon létre kulcsot. Minden kéréshez csatolja.
Authorization: Bearer gsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
A kulcsot csak szerveroldalon használja. Ha böngészőben futó JavaScriptbe ágyazza, mások is felhasználhatják.
A {source} helyére az alábbiak egyikét írja.
| source | Visszaadott adat |
|---|---|
google | Google keresési javaslatok |
bing | Bing keresési javaslatok |
youtube | YouTube keresési javaslatok |
amazon | Amazon keresési javaslatok a lang és a country paraméterrel kiválasztott piactérről (Amazon.com, Amazon.co.uk, Amazon.de, Amazon.co.jp stb.) |
ebay | eBay keresési javaslatok a lang és a country paraméterrel kiválasztott oldalról (ebay.com, ebay.co.uk, ebay.de, ebay.fr stb.; en, de, fr, it, es, nl, pl) |
shopee | Shopee keresési javaslatok a lang és a country paraméterrel kiválasztott oldalról (shopee.tw, shopee.sg, shopee.com.my, shopee.ph, shopee.co.id, shopee.vn, shopee.co.th, shopee.com.br stb.; zh-tw, en, ms, fil, id, vi, th, pt) |
duckduckgo | DuckDuckGo keresési javaslatok (lang=ja esetén japán javaslatok) |
baidu | Baidu keresési javaslatok (zh, ja, en) |
yandex | Yandex keresési javaslatok (ru, tr, kk, uz) |
naver | Naver keresési javaslatok (ko) |
daum | Daum keresési javaslatok (ko) |
yahoo | Yahoo! JAPAN keresési javaslatok (csak Japán) · zh-tw: Yahoo奇摩 (Yahoo! Tajvan) |
rakuten | Rakuten Ichiba keresési javaslatok (csak Japán) |
| Paraméter | Leírás |
|---|---|
q (kötelező) | Kulcsszó (1–60 karakter). A teljes és fél szélességű karaktereket, a kis- és nagybetűket, valamint a szóközöket normalizáljuk. |
lang | ja (alapértelmezett; a meglévő felhasználók miatt nem változtattuk meg, de javasolt kifejezetten megadni), en, ru, ko, zh és a webhely többi nyelvkódja (összesen 50). A ja japán kana szótagokkal bővít (nihongo), a többi nyelv szóközzel és saját betűivel (native). Az en esetén egyik bővítés sincs. |
country | Ország / piac (nem kötelező, ISO 3166-1 alpha-2). en: us (alapértelmezett), 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 stb. Az Amazonra (piactér), a Bingre, a DuckDuckGóra, a Google-ra és a YouTube-ra hat. Az Amazon, a Bing és a DuckDuckGo szorosan követi a megadott országot; a Google és a YouTube is igazodik hozzá, de a lekérés helyének hatása megmaradhat. |
group | all (alapértelmezett) vagy az itself,nihongo,native,alphabet,number elemek vesszővel elválasztott listája. |
flat | 1 esetén egyetlen, ismétlődésektől mentes suggestions tömböt ad vissza. |
Egy még le nem kért kulcsszó lekérése néhány tíz másodpercig tart, ezért az API először 202 kódot ad vissza, és sorba állítja a kérést. retry_after_seconds után küldje el újra ugyanazt a kérést: ha az adatok elkészültek, 200 kóddal megkapja őket. A lekért adatokat 7 napig gyorsítótárazzuk; lejárat után a frissítés idejére a régi adatokat adjuk vissza "stale": true jelöléssel. A gyorsítótár minden source, q és lang kombinációhoz külön tárolódik.
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 (sorban)
{ "ok": true, "status": "queued", "source": "google", "lang": "en", "country": "us", "queue_position": 3, "retry_after_seconds": 24, ... }
// 200 (kész)
{ "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", "..."] }
GET /api/v1/usage — A kulcs elmúlt 30 napi használata és a csomag korlátai (hitelesítés szükséges)GET /api/v1/status — Sorhossz és a workerek állapota (hitelesítés nélkül)| Tétel | Korlát |
|---|---|
| Kérés/perc | 30 |
| Kérés/nap (UTC) | 1,000 |
| Új (gyorsítótárban nem lévő) kulcsszó/nap | 20 Forrásonként (source) számoljuk; a már lekért kulcsszavak nem számítanak bele. |
Túllépéskor az API 429 kódot és Retry-After fejlécet ad vissza. Minden válasz tartalmazza az X-RateLimit-Limit / Remaining / Reset és az X-Daily-Limit / X-Daily-Remaining fejléceket.
| HTTP | code | Jelentés |
|---|---|---|
| 400 | invalid_query / invalid_lang / invalid_country / invalid_group / source_not_offered | Érvénytelen paraméter (ide tartozik az adott nyelven nem elérhető source is) |
| 401 | invalid_api_key | Hiányzó vagy érvénytelen kulcs |
| 404 | not_found | Érvénytelen source vagy útvonal |
| 429 | rate_limited / daily_quota_exceeded / new_keyword_quota_exceeded | Korlát túllépve (lásd Retry-After) |
| 502 | upstream_failed | A lekérés sikertelen (egy óra múlva újrapróbálható) |
| 503 | queue_full | Túlterhelés (lásd Retry-After) |
Magasabb korlátok, kereskedelmi felhasználás vagy hibabejelentés ügyében írjon közvetlenül az üzemeltetőnek (Yuki Nakazawa) Telegramon vagy X-en privát üzenetben. Angolul és japánul válaszol.
Felhasználási feltételek (angolul) · Adatvédelmi irányelvek (angolul)