یک JSON API که پیشنهادهای جست‌وجوی Google، Bing، YouTube، Amazon، eBay، Shopee، Rakuten Ichiba، Yahoo!، DuckDuckGo، Baidu، Yandex، Naver و Daum را (همراه با گسترش) به 50 زبان سایت برمی‌گرداند. ژاپنی با کانا (あ–ん)، A–Z و 0–9 گسترش داده می‌شود و زبان‌های دیگر با فاصله به‌علاوه حروف خود آن زبان، A–Z و 0–9. می‌توانید با پلن رایگان شروع کنید (تعرفه‌ها).
کلید API الزامی است. پس از ورود، می‌توانید از گزینه «API» در منوی کاربری کلید بسازید. کلید را همراه همه درخواست‌ها ارسال کنید.
Authorization: Bearer gsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
از کلید فقط در سمت سرور استفاده کنید (اگر آن را در JavaScript مرورگر قرار دهید، دیگران می‌توانند از آن استفاده کنند).
برای {source} یکی از مقادیر زیر را تعیین کنید.
| source | خروجی |
|---|---|
google | پیشنهادهای جست‌وجوی Google |
bing | پیشنهادهای جست‌وجوی Bing |
youtube | پیشنهادهای جست‌وجوی YouTube |
amazon | پیشنهادهای جست‌وجوی Amazon؛ بازار را با lang و country انتخاب می‌کنید (Amazon.com، Amazon.co.uk، Amazon.de، Amazon.co.jp و غیره) |
ebay | پیشنهادهای جست‌وجوی eBay؛ سایت را با lang و country انتخاب می‌کنید (ebay.com، ebay.co.uk، ebay.de، ebay.fr و غیره؛ en، de، fr، it، es، nl، pl) |
shopee | پیشنهادهای جست‌وجوی Shopee؛ سایت را با lang و country انتخاب می‌کنید (shopee.tw، shopee.sg، shopee.com.my، shopee.ph، shopee.co.id، shopee.vn، shopee.co.th، shopee.com.br و غیره؛ zh-tw، en، ms، fil، id، vi، th، pt) |
duckduckgo | پیشنهادهای جست‌وجوی DuckDuckGo (lang=ja پیشنهادهای ویژه ژاپن را برمی‌گرداند) |
baidu | پیشنهادهای جست‌وجوی Baidu (zh، ja، en) |
yandex | پیشنهادهای جست‌وجوی Yandex (ru، tr، kk، uz) |
naver | پیشنهادهای جست‌وجوی Naver (ko) |
daum | پیشنهادهای جست‌وجوی Daum (ko) |
yahoo | پیشنهادهای جست‌وجوی Yahoo! JAPAN (ویژه ژاپن) · zh-tw: Yahoo奇摩 (Yahoo! تایوان) |
rakuten | پیشنهادهای جست‌وجوی Rakuten Ichiba (ویژه ژاپن) |
| پارامتر | توضیح |
|---|---|
q (الزامی) | کلمه کلیدی (1 تا 60 نویسه). نویسه‌های تمام‌عرض/نیم‌عرض، حروف بزرگ و کوچک و فاصله‌ها یکسان‌سازی می‌شوند. |
lang | ja (پیش‌فرض؛ به خاطر کاربران فعلی تغییر نکرده، اما بهتر است صریحاً تعیین شود)، en، ru، ko، zh و دیگر کدهای 50 زبان سایت. ja با کانای ژاپنی (nihongo) و زبان‌های دیگر با فاصله به‌علاوه حروف خود زبان (native) گسترش داده می‌شوند. en هیچ‌یک از این دو گسترش را ندارد. |
country | کشور/بازار (اختیاری، کد دوحرفی ISO 3166-1). en: us (پیش‌فرض)، 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 و غیره. روی Amazon (بازار)، Bing، DuckDuckGo، Google و YouTube اثر دارد. Amazon، Bing و DuckDuckGo دقیقاً از کشور تعیین‌شده پیروی می‌کنند. Google و YouTube هم با کشور تطبیق داده می‌شوند، اما ممکن است تأثیر منطقه‌ای که درخواست از آن ارسال می‌شود همچنان باقی بماند. |
group | all (پیش‌فرض) یا فهرستی جداشده با کاما از itself,nihongo,native,alphabet,number. |
flat | با 1، نتیجه به صورت یک آرایه suggestions بدون موارد تکراری برگردانده می‌شود. |
دریافت کلمه کلیدی‌ای که هنوز دریافت نشده چند ده ثانیه طول می‌کشد، بنابراین API ابتدا 202 برمی‌گرداند و آن را در صف قرار می‌دهد. پس از retry_after_seconds، همان درخواست را دوباره ارسال کنید؛ اگر داده آماده باشد، با 200 برگردانده می‌شود. داده‌های دریافت‌شده 7 روز در کش می‌مانند و پس از انقضا، تا زمانی که دوباره دریافت شوند، داده قدیمی با "stale": true برگردانده می‌شود. کش برای هر ترکیب source، q و 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 (در صف)
{ "ok": true, "status": "queued", "source": "google", "lang": "en", "country": "us", "queue_position": 3, "retry_after_seconds": 24, ... }
// 200 (آماده)
{ "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 — میزان استفاده از کلید شما در 30 روز گذشته و سقف‌های پلن (نیازمند احراز هویت)GET /api/v1/status — عمق صف و وضعیت پردازشگرها (بدون نیاز به احراز هویت)| مورد | سقف |
|---|---|
| درخواست در دقیقه | 30 |
| درخواست در روز (UTC) | 1,000 |
| کلمه کلیدی جدید (کش‌نشده) در روز | 20 * برای هر source جداگانه شمرده می‌شود و کلمات کلیدی قبلاً دریافت‌شده از سهمیه کم نمی‌کنند |
در صورت عبور از سقف، 429 همراه با Retry-After برگردانده می‌شود. همه پاسخ‌ها هدرهای X-RateLimit-Limit / Remaining / Reset و X-Daily-Limit / X-Daily-Remaining را دارند.
| HTTP | code | معنی |
|---|---|---|
| 400 | invalid_query / invalid_lang / invalid_country / invalid_group / source_not_offered | پارامتر نامعتبر (از جمله مقدار source که برای آن زبان ارائه نمی‌شود) |
| 401 | invalid_api_key | کلید وجود ندارد یا نامعتبر است |
| 404 | not_found | source یا مسیر نامعتبر |
| 429 | rate_limited / daily_quota_exceeded / new_keyword_quota_exceeded | عبور از سقف (به Retry-After مراجعه کنید) |
| 502 | upstream_failed | دریافت ناموفق (پس از 1 ساعت می‌توانید دوباره تلاش کنید) |
| 503 | queue_full | سرویس شلوغ است (به Retry-After مراجعه کنید) |
برای افزایش سقف‌ها، مشاوره درباره استفاده تجاری یا گزارش خطا، مستقیماً از طریق Telegram یا پیام خصوصی X با گرداننده سرویس (Yuki Nakazawa) تماس بگیرید. به زبان‌های ژاپنی و انگلیسی پاسخ داده می‌شود.
شرایط استفاده (English) · سیاست حریم خصوصی (English)