Suggest API v1

API JSON yang memulangkan cadangan carian (termasuk pengembangan) daripada Google, Bing, YouTube, Amazon, eBay, Shopee, Rakuten Ichiba, Yahoo!, DuckDuckGo, Baidu, Yandex, Naver dan Daum dalam 50 bahasa laman ini. Bahasa Jepun dikembangkan dengan kana (あ–ん), A–Z dan 0–9, manakala bahasa lain dengan ruang serta huruf khas bahasa itu, A–Z dan 0–9. Anda boleh bermula dengan pelan percuma (harga).

Pengesahan

Kunci API diperlukan. Log masuk, kemudian jana kunci melalui “API” dalam menu pengguna. Sertakan kunci dalam setiap permintaan.

Authorization: Bearer gsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Gunakan kunci dari pelayan Anda sahaja (jika dibenamkan dalam JavaScript pelayar, orang lain boleh menggunakannya).

GET /api/v1/{source}/suggest

Tetapkan {source} kepada salah satu nilai berikut.

source	Sasaran
`google`	Cadangan carian Google
`bing`	Cadangan carian Bing
`youtube`	Cadangan carian YouTube
`amazon`	Cadangan carian Amazon. Pilih pasaran dengan `lang` dan `country` (Amazon.com, Amazon.co.uk, Amazon.de, Amazon.co.jp dan lain-lain)
`ebay`	Cadangan carian eBay. Pilih laman dengan `lang` dan `country` (ebay.com, ebay.co.uk, ebay.de, ebay.fr dan lain-lain; `en`, `de`, `fr`, `it`, `es`, `nl`, `pl`)
`shopee`	Cadangan carian Shopee. Pilih laman dengan `lang` dan `country` (shopee.tw, shopee.sg, shopee.com.my, shopee.ph, shopee.co.id, shopee.vn, shopee.co.th, shopee.com.br dan lain-lain; `zh-tw`, `en`, `ms`, `fil`, `id`, `vi`, `th`, `pt`)
`duckduckgo`	Cadangan carian DuckDuckGo (`lang=ja` memulangkan cadangan untuk Jepun)
`baidu`	Cadangan carian Baidu (`zh`, `ja`, `en`)
`yandex`	Cadangan carian Yandex (`ru`, `tr`, `kk`, `uz`)
`naver`	Cadangan carian Naver (`ko`)
`daum`	Cadangan carian Daum (`ko`)
`yahoo`	Cadangan carian Yahoo! JAPAN (untuk Jepun) · `zh-tw`: Yahoo奇摩 (Taiwan)
`rakuten`	Cadangan carian Rakuten Ichiba (untuk Jepun)

Parameter	Penerangan
`q` (wajib)	Kata kunci (1–60 aksara). Aksara lebar penuh/separuh lebar, huruf besar/kecil dan ruang dinormalkan.
`lang`	`ja` (lalai; dikekalkan untuk pengguna sedia ada, tetapi disyorkan untuk dinyatakan secara eksplisit), `en`, `ru`, `ko`, `zh` dan kod lain bagi 50 bahasa laman ini. `ja` dikembangkan dengan kana Jepun (`nihongo`), manakala bahasa lain dengan ruang serta huruf khas bahasa itu (`native`). `en` tidak mempunyai pengembangan kana mahupun huruf khas.
`country`	Negara / pasaran (tidak wajib, ISO 3166-1 dua huruf). `en`: us (lalai), 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; dan lain-lain. Berkesan untuk Amazon (pasaran), Bing, DuckDuckGo, Google dan YouTube. Amazon, Bing dan DuckDuckGo mematuhi negara yang ditetapkan dengan ketat. Google dan YouTube juga menyesuaikan dengan negara, tetapi lokasi asal permintaan mungkin masih mempengaruhi hasil.
`group`	`all` (lalai) atau senarai yang dipisahkan dengan koma daripada `itself,nihongo,native,alphabet,number`.
`flat`	`1` memulangkan satu tatasusunan `suggestions` tanpa pendua.

Cara aliran tak segerak berfungsi

Mengambil kata kunci yang belum pernah diambil memerlukan beberapa puluh saat, jadi API terlebih dahulu memulangkan 202 dan memasukkannya ke dalam baris gilir. Hantar permintaan yang sama sekali lagi selepas retry_after_seconds; jika data sudah sedia, Anda akan menerima 200 berserta data. Data yang sudah diambil disimpan dalam cache selama 7 hari. Selepas tamat tempoh, data lama dipulangkan dengan "stale": true semasa data sedang diambil semula. Cache adalah berasingan bagi setiap gabungan source, q dan 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 (dalam baris gilir)
{ "ok": true, "status": "queued", "source": "google", "lang": "en", "country": "us", "queue_position": 3, "retry_after_seconds": 24, ... }

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

Endpoint lain

GET /api/v1/usage — Penggunaan kunci Anda dalam 30 hari lepas dan had pelan Anda (memerlukan pengesahan)
GET /api/v1/status — Panjang baris gilir dan status worker (tanpa pengesahan)

Had (pelan percuma)

Perkara	Had
Permintaan seminit	30
Permintaan sehari (UTC)	1,000
Kata kunci baharu (belum dalam cache) sehari	20 Dikira berasingan bagi setiap source. Kata kunci yang sudah diambil tidak dikira.

Apabila had dilampaui, API memulangkan 429 berserta Retry-After. Setiap respons menyertakan X-RateLimit-Limit / Remaining / Reset dan X-Daily-Limit / X-Daily-Remaining.

Ralat

HTTP	code	Maksud
400	invalid_query / invalid_lang / invalid_country / invalid_group / source_not_offered	Parameter tidak sah (termasuk `source` yang tidak ditawarkan untuk bahasa tersebut)
401	invalid_api_key	Kunci tiada atau tidak sah
404	not_found	`source` atau laluan tidak sah
429	rate_limited / daily_quota_exceeded / new_keyword_quota_exceeded	Had dilampaui (lihat `Retry-After`)
502	upstream_failed	Gagal mengambil data (boleh dicuba semula selepas satu jam)
503	queue_full	Sistem sibuk (lihat `Retry-After`)

Hubungi kami

Untuk menaikkan had, penggunaan komersial atau laporan pepijat, hubungi pengendali (Yuki Nakazawa) terus melalui Telegram atau DM di X. Kami membalas dalam bahasa Jepun dan bahasa Inggeris.

Sebelum menggunakan API

Had pelan percuma boleh berubah tanpa notis. Untuk pelan berbayar, lihat halaman harga.
Data ini berdasarkan respons cadangan carian awam setiap perkhidmatan. Ketepatan dan kesinambungan (SLA) tidak dijamin.

Terma Perkhidmatan (English) · Dasar Privasi (English)