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 кодына енгізсеңіз, оны бөгде адамдар пайдаланып кетуі мүмкін).
{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奇摩 (Тайвань) |
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 үшін бөлек есептеледі; бұрын алынған кілт сөздер есептелмейді |
Лимит асып кетсе, API 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 жеке хабарламасы арқылы тікелей жазыңыз. Ағылшын немесе жапон тілінде жауап береміз.