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奇摩 (Yahoo! ታይዋን)
`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` ድርድር (array) ይመልሳል።

ያልተመሳሰለ (asynchronous) አሠራር

ገና ያልተገኘ ቁልፍ ቃልን ማምጣት በአስር የሚቆጠሩ ሰከንዶች ስለሚወስድ፣ 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", "..."] }

ሌሎች endpoints

GET /api/v1/usage — ባለፉት 30 ቀናት የቁልፍዎ አጠቃቀም እና የዕቅድዎ ገደቦች (ማረጋገጫ ያስፈልጋል)
GET /api/v1/status — የወረፋ ርዝመት እና የworker ሁኔታ (ማረጋገጫ አያስፈልግም)

ገደቦች (ነፃ ዕቅድ)

ንጥል	ገደብ
ጥያቄዎች/ደቂቃ	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` ወይም path
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) ዋስትና አይሰጥም።

የአገልግሎት ውል (English) · የግላዊነት ፖሊሲ (English)