Suggest API v1

API ya JSON inayorudisha mapendekezo ya utafutaji (pamoja na upanuzi) ya Google, Bing, YouTube, Amazon, eBay, Shopee, Rakuten Ichiba, Yahoo!, DuckDuckGo, Baidu, Yandex, Naver na Daum katika lugha 50 za tovuti. Kijapani hupanuliwa kwa kana (あ–ん), A–Z na 0–9, na lugha nyingine kwa nafasi pamoja na herufi za lugha husika, A–Z na 0–9. Unaweza kuanza na mpango wa bila malipo (bei).

Uthibitishaji

Ufunguo wa API unahitajika. Ingia, kisha utengeneze ufunguo kupitia “API” kwenye menyu ya mtumiaji. Utume pamoja na kila ombi.

Authorization: Bearer gsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Tumia ufunguo kutoka kwenye seva yako pekee (ukiuweka ndani ya JavaScript ya kivinjari, watu wengine wanaweza kuutumia).

GET /api/v1/{source}/suggest

Weka {source} kuwa mojawapo ya yafuatayo.

source	Kinachorudishwa
`google`	Mapendekezo ya Google
`bing`	Mapendekezo ya Bing
`youtube`	Mapendekezo ya YouTube
`amazon`	Mapendekezo ya Amazon. Chagua soko kwa `lang` na `country` (Amazon.com, Amazon.co.uk, Amazon.de, Amazon.co.jp na mengineyo)
`ebay`	Mapendekezo ya eBay. Chagua tovuti kwa `lang` na `country` (ebay.com, ebay.co.uk, ebay.de, ebay.fr na nyinginezo; `en`, `de`, `fr`, `it`, `es`, `nl`, `pl`)
`shopee`	Mapendekezo ya Shopee. Chagua tovuti kwa `lang` na `country` (shopee.tw, shopee.sg, shopee.com.my, shopee.ph, shopee.co.id, shopee.vn, shopee.co.th, shopee.com.br na nyinginezo; `zh-tw`, `en`, `ms`, `fil`, `id`, `vi`, `th`, `pt`)
`duckduckgo`	Mapendekezo ya DuckDuckGo (`lang=ja` hurudisha mapendekezo ya Japani)
`baidu`	Mapendekezo ya Baidu (`zh`, `ja`, `en`)
`yandex`	Mapendekezo ya Yandex (`ru`, `tr`, `kk`, `uz`)
`naver`	Mapendekezo ya Naver (`ko`)
`daum`	Mapendekezo ya Daum (`ko`)
`yahoo`	Mapendekezo ya utafutaji ya Yahoo! JAPAN (kwa Japani) · `zh-tw`: Yahoo奇摩 (Taiwan)
`rakuten`	Mapendekezo ya Rakuten Ichiba (kwa Japani)

Kigezo	Maelezo
`q` (lazima)	Neno muhimu (herufi 1–60). Herufi za upana kamili/nusu, herufi kubwa/ndogo na nafasi husawazishwa.
`lang`	`ja` (chaguomsingi; haijabadilishwa kwa ajili ya watumiaji waliopo, lakini inapendekezwa kuibainisha wazi), `en`, `ru`, `ko`, `zh` na misimbo mingine ya lugha 50 za tovuti. `ja` hupanuliwa kwa kana (`nihongo`), na lugha nyingine kwa nafasi pamoja na herufi zake (`native`). `en` haina upanuzi wa kana wala wa herufi za lugha.
`country`	Nchi / soko (si lazima, ISO 3166-1 herufi 2). `en`: us (chaguomsingi), 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; na mengineyo. Hutumika kwa Amazon (soko), Bing, DuckDuckGo, Google na YouTube. Amazon, Bing na DuckDuckGo hufuata kwa karibu nchi iliyobainishwa. Google na YouTube pia hufuata nchi, lakini mahali ombi linapotumwa kutoka bado kunaweza kuathiri matokeo.
`group`	`all` (chaguomsingi) au orodha iliyotenganishwa kwa koma ya `itself,nihongo,native,alphabet,number`.
`flat`	`1` hurudisha safu moja ya `suggestions` bila marudio.

Jinsi mtiririko usiolandanishwa (asynchronous) unavyofanya kazi

Kukusanya neno muhimu ambalo bado halijapatikana huchukua makumi ya sekunde, kwa hiyo API kwanza hurudisha 202 na kuliweka kwenye foleni. Tuma ombi lilelile tena baada ya retry_after_seconds; data ikiwa tayari, utapokea 200 pamoja na data. Data iliyokusanywa huhifadhiwa kwenye akiba kwa siku 7. Muda huo ukiisha, data ya zamani hurudishwa pamoja na "stale": true wakati inakusanywa upya. Akiba ni tofauti kwa kila mchanganyiko wa source, q na 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 (kwenye foleni)
{ "ok": true, "status": "queued", "source": "google", "lang": "en", "country": "us", "queue_position": 3, "retry_after_seconds": 24, ... }

// 200 (tayari)
{ "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", "..."] }

Endpoint nyingine

GET /api/v1/usage — Matumizi ya ufunguo wako katika siku 30 zilizopita na vikomo vya mpango wako (uthibitishaji unahitajika)
GET /api/v1/status — Urefu wa foleni na hali ya worker (bila uthibitishaji)

Vikomo (mpango wa bila malipo)

Kipengele	Kikomo
Maombi kwa dakika	30
Maombi kwa siku (UTC)	1,000
Maneno muhimu mapya (yasiyo kwenye akiba) kwa siku	20 Huhesabiwa kando kwa kila source. Maneno muhimu ambayo tayari yamepatikana hayahesabiwi.

Kikomo kikipitwa, API hurudisha 429 pamoja na Retry-After. Kila jibu lina X-RateLimit-Limit / Remaining / Reset na X-Daily-Limit / X-Daily-Remaining.

Hitilafu

HTTP	code	Maana
400	invalid_query / invalid_lang / invalid_country / invalid_group / source_not_offered	Kigezo batili (ikiwemo `source` isiyotolewa kwa lugha hiyo)
401	invalid_api_key	Ufunguo haupo au ni batili
404	not_found	`source` au njia (path) batili
429	rate_limited / daily_quota_exceeded / new_keyword_quota_exceeded	Kikomo kimepitwa (angalia `Retry-After`)
502	upstream_failed	Ukusanyaji umeshindikana (unaweza kujaribu tena baada ya saa moja)
503	queue_full	Seva ina shughuli nyingi (angalia `Retry-After`)

Wasiliana nasi

Kwa vikomo vya juu zaidi, matumizi ya kibiashara au ripoti za hitilafu, mwandikie moja kwa moja mwendeshaji (Yuki Nakazawa) kupitia Telegram au ujumbe wa moja kwa moja (DM) kwenye X. Tunajibu kwa Kijapani na Kiingereza.

Kabla ya kutumia API

Vikomo vya mpango wa bila malipo vinaweza kubadilika bila taarifa. Kwa mipango ya kulipia, angalia ukurasa wa bei.
Data inatokana na majibu ya umma ya mapendekezo ya kila huduma. Usahihi na uendelevu (SLA) havihakikishwi.

Masharti ya Huduma (English) · Sera ya Faragha (English)