Suggest API v1

JSON API koji na 50 jezika sajta vraća predloge pretrage (uključujući proširenja) sa Googlea, Binga, YouTubea, Amazona, eBaya, Shopeeja, Rakuten Ichibe, Yahoo!-a, DuckDuckGoa, Baidua, Yandexa, Navera i Dauma. Japanski se proširuje kanom (あ–ん), A–Z i 0–9, a ostali jezici razmakom i sopstvenim slovima jezika (u srpskom na primer č ć đ š ž), A–Z i 0–9. Možete da počnete sa besplatnim paketom (cene).

Autentifikacija

Potreban je API ključ. Prijavite se i napravite ključ u korisničkom meniju pod „API“. Šaljite ga uz svaki zahtev.

Authorization: Bearer gsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Ključ koristite samo sa svog servera. Ako ga ugradite u JavaScript u veb-pregledaču, mogu da ga koriste i drugi.

GET /api/v1/{source}/suggest

Za {source} navedite jednu od sledećih vrednosti.

source	Vraća
`google`	Google predlozi pretrage
`bing`	Bing predlozi pretrage
`youtube`	YouTube predlozi pretrage
`amazon`	Amazon predlozi pretrage. Tržište birate parametrima `lang` i `country` (Amazon.com, Amazon.co.uk, Amazon.de, Amazon.co.jp i drugi)
`ebay`	eBay predlozi pretrage. Sajt birate parametrima `lang` i `country` (ebay.com, ebay.co.uk, ebay.de, ebay.fr i drugi; `en`, `de`, `fr`, `it`, `es`, `nl`, `pl`)
`shopee`	Shopee predlozi pretrage. Sajt birate parametrima `lang` i `country` (shopee.tw, shopee.sg, shopee.com.my, shopee.ph, shopee.co.id, shopee.vn, shopee.co.th, shopee.com.br i drugi; `zh-tw`, `en`, `ms`, `fil`, `id`, `vi`, `th`, `pt`)
`duckduckgo`	DuckDuckGo predlozi pretrage (`lang=ja` vraća predloge za Japan)
`baidu`	Baidu predlozi pretrage (`zh`, `ja`, `en`)
`yandex`	Yandex predlozi pretrage (`ru`, `tr`, `kk`, `uz`)
`naver`	Naver predlozi pretrage (`ko`)
`daum`	Daum predlozi pretrage (`ko`)
`yahoo`	Predlozi pretrage Yahoo! JAPAN (samo Japan) · `zh-tw`: Yahoo奇摩 (Yahoo! Tajvan)
`rakuten`	Predlozi pretrage Rakuten Ichibe (samo Japan)

Parametar	Opis
`q` (obavezno)	Ključna reč (1–60 znakova). Znakovi pune i polovične širine, velika i mala slova i razmaci se normalizuju.
`lang`	`ja` (podrazumevano; zadržano zbog postojećih klijenata, ali preporučujemo da ga izričito navedete), `en`, `ru`, `ko`, `zh` i ostale jezičke oznake sajta (ukupno 50). `ja` se proširuje kanom (`nihongo`), ostali jezici razmakom i sopstvenim slovima jezika (`native`). `en` nema ni jedno ni drugo.
`country`	Zemlja/tržište (neobavezno, ISO 3166-1, 2 slova). `en`: us (podrazumevano), 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 i drugi. Primenjuje se na Amazon (tržište), Bing, DuckDuckGo, Google i YouTube. Amazon, Bing i DuckDuckGo strogo prate izabranu zemlju. Google i YouTube se takođe prilagođavaju zemlji, ali na rezultate i dalje može da utiče lokacija sa koje se zahtev šalje.
`group`	`all` (podrazumevano) ili lista razdvojena zarezima iz `itself,nihongo,native,alphabet,number`.
`flat`	Uz `1` vraća se jedan niz `suggestions` bez duplikata.

Kako funkcioniše asinhroni tok

Preuzimanje ključne reči koja još nije preuzeta traje nekoliko desetina sekundi, pa API najpre vraća 202 i stavlja je u red čekanja. Posle retry_after_seconds ponovo pošaljite isti zahtev; kada podaci budu spremni, dobićete 200 sa rezultatima. Preuzeti podaci se čuvaju u kešu 7 dana. Nakon isteka stari podaci se vraćaju sa "stale": true dok se ponovo preuzimaju. Keš je zaseban za svaku kombinaciju source, q i 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 (u redu čekanja)
{ "ok": true, "status": "queued", "source": "google", "lang": "en", "country": "us", "queue_position": 3, "retry_after_seconds": 24, ... }

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

Ostale krajnje tačke

GET /api/v1/usage — Potrošnja Vašeg ključa u poslednjih 30 dana i ograničenja paketa (potrebna autentifikacija)
GET /api/v1/status — Dužina reda čekanja i stanje workera (bez autentifikacije)

Ograničenja (besplatni paket)

Stavka	Ograničenje
Zahteva u minutu	30
Zahteva dnevno (UTC)	1,000
Novih ključnih reči (van keša) dnevno	20 Broji se posebno za svaki source. Već preuzete ključne reči ne troše kvotu.

Pri prekoračenju API vraća 429 i Retry-After. Svaki odgovor sadrži X-RateLimit-Limit / Remaining / Reset i X-Daily-Limit / X-Daily-Remaining.

Greške

HTTP	code	Značenje
400	invalid_query / invalid_lang / invalid_country / invalid_group / source_not_offered	Neispravan parametar (uključujući `source` koji nije dostupan za taj jezik)
401	invalid_api_key	Ključ nedostaje ili je neispravan
404	not_found	Neispravan `source` ili putanja
429	rate_limited / daily_quota_exceeded / new_keyword_quota_exceeded	Prekoračeno ograničenje (vidi `Retry-After`)
502	upstream_failed	Preuzimanje nije uspelo (ponovni pokušaj je moguć posle 1 sata)
503	queue_full	Preopterećenje (vidi `Retry-After`)

Kontakt

Za veća ograničenja, komercijalnu upotrebu ili prijavu grešaka obratite se direktno operateru servisa (Yuki Nakazawa) preko Telegrama ili direktne poruke na X-u. Odgovaramo na japanskom i engleskom.

Pre korišćenja

Ograničenja besplatnog paketa mogu da se promene bez najave. Plaćene pakete pogledajte na stranici sa cenama.
Podaci se zasnivaju na javnim odgovorima sa predlozima pojedinih servisa. Tačnost i kontinuitet (SLA) nisu zagarantovani.

Uslovi korišćenja (na engleskom) · Politika privatnosti (na engleskom)