واجهة JSON API تعيد اقتراحات البحث (الإكمال التلقائي) من Google وBing وYouTube وAmazon وRakuten Ichiba وYahoo! وDuckDuckGo وBaidu وYandex وNaver وDaum مع التوسيعات، بجميع لغات الموقع العشرين. تُوسَّع اليابانية بمقاطع الكانا (あ–ん) و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 (ja: Amazon.co.jp؛ اللغات الأخرى: المتجر الرئيسي لتلك اللغة) |
rakuten | اقتراحات Rakuten Ichiba (اليابان) |
yahoo | اقتراحات بحث Yahoo! |
duckduckgo | اقتراحات DuckDuckGo (مع lang=ja تُعاد اقتراحات موجهة لليابان) |
baidu | اقتراحات Baidu (zh، zh-tw، ja، en) |
yandex | اقتراحات Yandex (ru، uk، tr) |
naver | اقتراحات Naver (ko) |
daum | اقتراحات Daum (ko) |
| المعامل | الوصف |
|---|---|
q (إلزامي) | الكلمة المفتاحية (من 1 إلى 60 حرفًا). يُوحَّد شكل الأحرف كاملة العرض ونصف العرض وحالة الأحرف والمسافات. |
lang | ja (افتراضي) وen وru وko وzh وسائر رموز لغات الموقع (20 لغة). يضيف ja التوسيع بالكانا (nihongo)، وتضيف اللغات الأخرى مسافة مع حروفها الخاصة (native). أما en فليس له أيٌّ منهما. |
group | all (افتراضي) أو قائمة مفصولة بفواصل من itself,nihongo,native,alphabet,number. |
flat | القيمة 1 تعيد مصفوفة suggestions واحدة بعد حذف التكرارات. |
يستغرق جلب كلمة مفتاحية غير مخزنة مؤقتًا عشرات الثواني، لذا تعيد الواجهة أولًا 202 وتضعها في قائمة الانتظار. أعد إرسال الطلب نفسه بعد retry_after_seconds ثانية؛ وعندما تكون البيانات جاهزة تحصل على 200 مع النتائج. تُخزَّن النتائج مؤقتًا لمدة 7 أيام، وبعد انتهاء صلاحيتها تُعاد البيانات القديمة مع "stale": true أثناء تحديثها. ذاكرة التخزين المؤقت منفصلة لكل تركيبة من source وq وlang.
curl -H "Authorization: Bearer $KEY" \ "https://gstudio1.com/api/v1/google/suggest?q=%E3%83%A9%E3%83%B3%E3%83%8B%E3%83%B3%E3%82%B0&flat=1" curl -H "Authorization: Bearer $KEY" \ "https://gstudio1.com/api/v1/rakuten/suggest?q=%E3%83%A9%E3%83%B3%E3%83%8B%E3%83%B3%E3%82%B0&flat=1"
// 202 (في الانتظار)
{ "ok": true, "status": "queued", "source": "google", "queue_position": 3, "retry_after_seconds": 24, ... }
// 200 (جاهز)
{ "ok": true, "status": "ready", "query": "ランニング", "source": "google", "fetched_at": "2026-09-19T01:02:03Z",
"stale": false, "count": 412, "suggestions": ["ランニング シューズ", "..."] }
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_group | معامل غير صالح (بما في ذلك 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) |
شروط الخدمة (English) · سياسة الخصوصية (English)