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 | השליפה נכשלה (אפשר לנסות שוב בעוד שעה) |
| 503 | queue_full | עומס (ראו Retry-After) |
לבקשות להגדלת המגבלות, לשימוש מסחרי או לדיווח על תקלות, אפשר לפנות ישירות למפעיל (Yuki Nakazawa) ב-Telegram או בהודעה פרטית ב-X. התשובות ביפנית ובאנגלית.
תנאי שימוש (English) · מדיניות פרטיות (English)