Suggest API v1

Google, Bing, YouTube, Amazon, eBay, Shopee, Rakuten Ichiba, Yahoo!, DuckDuckGo, Baidu, Yandex, Naver र Daum का सुझावहरू (विस्तारसहित) साइटका 50 भाषामा निकाल्ने JSON API। जापानी भाषामा काना (あ–ん), A–Z र 0–9 ले, अन्य भाषामा स्पेस र सम्बन्धित भाषाका आफ्नै अक्षर (जस्तै नेपालीमा क–ह), A–Z र 0–9 ले विस्तार गरिन्छ। निःशुल्क प्लानबाट सुरु गर्न सकिन्छ (मूल्य)।

प्रमाणीकरण

API की अनिवार्य छ। लग इन गरेपछि प्रयोगकर्ता मेनुको "API" बाट की बनाउन सकिन्छ। हरेक अनुरोधमा यो की पठाउनुहोस्।

Authorization: Bearer gsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

की सर्भरबाट मात्र प्रयोग गर्नुहोस् (ब्राउजरको JavaScript मा राख्नुभयो भने अरूले यसको प्रयोग गर्न सक्छन्)।

GET /api/v1/{source}/suggest

{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! Taiwan
`rakuten`	Rakuten Ichiba सुझाव (जापानका लागि)

प्यारामिटर	विवरण
`q` (अनिवार्य)	किवर्ड (1–60 अक्षर)। फुल-विड्थ/हाफ-विड्थ, ठूला/साना अक्षर र स्पेस सामान्यीकरण गरिन्छ।
`lang`	`ja` (पूर्वनिर्धारित; हालका प्रयोगकर्ताका लागि पूर्वनिर्धारित मान नबदलिएको हो, तर स्पष्ट रूपमा दिन सिफारिस गरिन्छ), `en`, `ru`, `ko`, `zh` आदि साइटका 50 भाषाका कोड। `ja` मा जापानी काना (`nihongo`) ले, अन्य भाषामा स्पेस र सम्बन्धित भाषाका आफ्नै अक्षर (`native`) ले विस्तार गरिन्छ। `en` मा काना वा आफ्नै अक्षरको विस्तार हुँदैन।
`country`	देश/बजार (वैकल्पिक, ISO 3166-1 का 2 अक्षरको कोड)। `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` हेर्नुहोस्)

सम्पर्क

सीमा बढाउने, व्यावसायिक प्रयोगबारे परामर्श वा त्रुटिको जानकारीका लागि सञ्चालक (Yuki Nakazawa) लाई Telegram वा X को DM मार्फत सिधै सम्पर्क गर्नुहोस्। जवाफ अङ्ग्रेजी वा जापानी भाषामा दिइन्छ।

प्रयोग गर्नुअघि

निःशुल्क प्लानका सीमा पूर्वसूचनाबिना परिवर्तन हुन सक्छन्। सशुल्क प्लानका लागि मूल्य पेज हेर्नुहोस्।
डेटा हरेक सेवाको सार्वजनिक सुझाव प्रतिक्रियामा आधारित छ; शुद्धता र निरन्तरता (SLA) को ग्यारेन्टी गरिँदैन।

सेवाका सर्तहरू · गोपनीयता नीति