Suggest API v1

JSON API koji na 50 jezika stranice vraća prijedloge pretraživanja (uključujući proširenja) s 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 vlastitim slovima jezika (u hrvatskom primjerice č ć đ š ž), A–Z i 0–9. Možete početi s besplatnim paketom (cijene).

Autentifikacija

Potreban je API ključ. Prijavite se i izradite ključ u korisničkom izborniku pod „API“. Šaljite ga uz svaki zahtjev.

Authorization: Bearer gsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Ključ koristite samo sa svojeg poslužitelja. Ako ga ugradite u JavaScript u pregledniku, mogu ga upotrijebiti i drugi.

GET /api/v1/{source}/suggest

Za {source} navedite jednu od sljedećih vrijednosti.

source	Vraća
`google`	Google prijedlozi pretraživanja
`bing`	Bing prijedlozi pretraživanja
`youtube`	YouTube prijedlozi pretraživanja
`amazon`	Amazon prijedlozi pretraživanja. Tržište birate parametrima `lang` i `country` (Amazon.com, Amazon.co.uk, Amazon.de, Amazon.co.jp i dr.)
`ebay`	eBay prijedlozi pretraživanja. Stranicu birate parametrima `lang` i `country` (ebay.com, ebay.co.uk, ebay.de, ebay.fr i dr.; `en`, `de`, `fr`, `it`, `es`, `nl`, `pl`)
`shopee`	Shopee prijedlozi pretraživanja. Stranicu 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 dr.; `zh-tw`, `en`, `ms`, `fil`, `id`, `vi`, `th`, `pt`)
`duckduckgo`	DuckDuckGo prijedlozi pretraživanja (`lang=ja` vraća prijedloge za Japan)
`baidu`	Baidu prijedlozi pretraživanja (`zh`, `ja`, `en`)
`yandex`	Yandex prijedlozi pretraživanja (`ru`, `tr`, `kk`, `uz`)
`naver`	Naver prijedlozi pretraživanja (`ko`)
`daum`	Daum prijedlozi pretraživanja (`ko`)
`yahoo`	Prijedlozi pretraživanja Yahoo! JAPAN (samo Japan) · `zh-tw`: Yahoo奇摩 (Yahoo! Tajvan)
`rakuten`	Prijedlozi pretraživanja Rakuten Ichibe (samo Japan)

Parametar	Opis
`q` (obavezno)	Ključna riječ (1–60 znakova). Znakovi pune i polovične širine, velika i mala slova te razmaci normaliziraju se.
`lang`	`ja` (zadano; zadržano radi postojećih klijenata, ali preporučujemo da ga izričito navedete), `en`, `ru`, `ko`, `zh` i ostale jezične oznake stranice (ukupno 50). `ja` se proširuje kanom (`nihongo`), ostali jezici razmakom i vlastitim slovima jezika (`native`). `en` nema ni jedno ni drugo.
`country`	Zemlja/tržište (neobavezno, ISO 3166-1, 2 slova). `en`: us (zadano), 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 dr. Primjenjuje se na Amazon (tržište), Bing, DuckDuckGo, Google i YouTube. Amazon, Bing i DuckDuckGo strogo slijede odabranu zemlju. Google i YouTube također se prilagođavaju zemlji, ali na rezultate i dalje može utjecati lokacija s koje se zahtjev šalje.
`group`	`all` (zadano) ili popis odvojen zarezima iz `itself,nihongo,native,alphabet,number`.
`flat`	Uz `1` vraća se jedan niz `suggestions` bez duplikata.

Kako funkcionira asinkroni tijek

Dohvaćanje ključne riječi koja još nije dohvaćena traje nekoliko desetaka sekundi, pa API najprije vraća 202 i stavlja je u red čekanja. Nakon retry_after_seconds ponovno pošaljite isti zahtjev; kada su podaci spremni, dobit ćete 200 s rezultatima. Dohvaćeni podaci čuvaju se u predmemoriji 7 dana. Nakon isteka stari se podaci vraćaju s "stale": true dok se ponovno dohvaćaju. Predmemorija je zasebna 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 točke

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

Ograničenja (besplatni paket)

Stavka	Ograničenje
Zahtjeva u minuti	30
Zahtjeva dnevno (UTC)	1,000
Novih ključnih riječi (izvan predmemorije) dnevno	20 Broji se zasebno za svaki source. Već dohvaćene ključne riječ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.

Pogreš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	Dohvaćanje nije uspjelo (ponovni pokušaj moguć nakon 1 sata)
503	queue_full	Preopterećenje (vidi `Retry-After`)

Kontakt

Za veća ograničenja, komercijalnu upotrebu ili prijavu pogrešaka obratite se izravno operateru usluge (Yuki Nakazawa) putem Telegrama ili izravne poruke na X-u. Odgovaramo na japanskom i engleskom.

Prije korištenja

Ograničenja besplatnog paketa mogu se promijeniti bez najave. Plaćene pakete pogledajte na stranici s cijenama.
Podaci se temelje na javnim odgovorima s prijedlozima pojedinih servisa. Točnost i kontinuitet (SLA) nisu zajamčeni.

Uvjeti korištenja (na engleskom) · Pravila privatnosti (na engleskom)