JSON-API, joka palauttaa Googlen, Bingin, YouTuben, Amazonin, eBayn, Shopeen, Rakuten Ichiban, Yahoo!:n, DuckDuckGon, Baidun, Yandexin, Naverin ja Daumin hakuehdotukset (laajennuksineen) sivuston 50 kielellä. Japani laajennetaan kana-merkeillä (あ–ん) sekä merkeillä A–Z ja 0–9, muut kielet välilyönnillä ja kielen omilla kirjaimilla (suomessa esimerkiksi ä ö å) sekä merkeillä A–Z ja 0–9. Voit aloittaa ilmaisella paketilla (hinnasto).
API-avain on pakollinen. Kirjaudu sisään ja luo avain käyttäjävalikon kohdasta ”API”. Lähetä avain jokaisen pyynnön mukana.
Authorization: Bearer gsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Käytä avainta vain palvelimeltasi. Jos upotat sen selaimen JavaScriptiin, muut voivat käyttää sitä.
Anna {source}-kohtaan jokin seuraavista arvoista.
| source | Palauttaa |
|---|---|
google | Google-hakuehdotukset |
bing | Bing-hakuehdotukset |
youtube | YouTube-hakuehdotukset |
amazon | Amazon-hakuehdotukset. Kauppapaikka valitaan parametreilla lang ja country (Amazon.com, Amazon.co.uk, Amazon.de, Amazon.co.jp ym.) |
ebay | eBay-hakuehdotukset. Sivusto valitaan parametreilla lang ja country (ebay.com, ebay.co.uk, ebay.de, ebay.fr ym.; en, de, fr, it, es, nl, pl) |
shopee | Shopee-hakuehdotukset. Sivusto valitaan parametreilla lang ja country (shopee.tw, shopee.sg, shopee.com.my, shopee.ph, shopee.co.id, shopee.vn, shopee.co.th, shopee.com.br ym.; zh-tw, en, ms, fil, id, vi, th, pt) |
duckduckgo | DuckDuckGo-hakuehdotukset (lang=ja palauttaa Japanin ehdotukset) |
baidu | Baidu-hakuehdotukset (zh, ja, en) |
yandex | Yandex-hakuehdotukset (ru, tr, kk, uz) |
naver | Naver-hakuehdotukset (ko) |
daum | Daum-hakuehdotukset (ko) |
yahoo | Yahoo! JAPANin hakuehdotukset (vain Japani) · zh-tw: Yahoo奇摩 (Yahoo! Taiwan) |
rakuten | Rakuten Ichiban hakuehdotukset (vain Japani) |
| Parametri | Kuvaus |
|---|---|
q (pakollinen) | Hakusana (1–60 merkkiä). Täysleveät ja puolileveät merkit, kirjainkoko ja välilyönnit normalisoidaan. |
lang | ja (oletus; säilytetty nykyisten asiakkaiden vuoksi, mutta suosittelemme antamaan sen erikseen), en, ru, ko, zh ja muut sivuston kielikoodit (yhteensä 50). ja laajennetaan kana-merkeillä (nihongo), muut kielet välilyönnillä ja kielen omilla kirjaimilla (native). Kielellä en ei ole kumpaakaan. |
country | Maa/markkina (valinnainen, ISO 3166-1, 2 kirjainta). en: us (oletus), 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 ym. Vaikuttaa Amazoniin (kauppapaikka), Bingiin, DuckDuckGoon, Googleen ja YouTubeen. Amazon, Bing ja DuckDuckGo noudattavat valittua maata tarkasti. Myös Google ja YouTube mukautuvat maahan, mutta niiden tuloksiin voi silti vaikuttaa se, mistä pyyntö lähetetään. |
group | all (oletus) tai pilkuin eroteltu luettelo arvoista itself,nihongo,native,alphabet,number. |
flat | Arvolla 1 palautetaan yksi suggestions-taulukko ilman kaksoiskappaleita. |
Hakusanan, jota ei ole vielä haettu, hakeminen kestää kymmeniä sekunteja, joten API palauttaa ensin koodin 202 ja lisää haun jonoon. Lähetä sama pyyntö uudelleen, kun retry_after_seconds on kulunut; kun tiedot ovat valmiina, saat koodin 200 ja tulokset. Haetut tiedot pidetään välimuistissa 7 päivää. Vanhentumisen jälkeen vanhat tiedot palautetaan merkinnällä "stale": true, kun niitä haetaan uudelleen. Välimuisti on erillinen jokaiselle source-, q- ja lang-yhdistelmälle.
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 (jonossa)
{ "ok": true, "status": "queued", "source": "google", "lang": "en", "country": "us", "queue_position": 3, "retry_after_seconds": 24, ... }
// 200 (valmis)
{ "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 — Avaimesi käyttö viimeisten 30 päivän ajalta ja pakettisi rajat (vaatii todennuksen)GET /api/v1/status — Jonon pituus ja workereiden tila (ei vaadi todennusta)| Kohde | Raja |
|---|---|
| Pyyntöä minuutissa | 30 |
| Pyyntöä päivässä (UTC) | 1,000 |
| Uutta (välimuistissa olematonta) hakusanaa päivässä | 20 Lasketaan source-kohtaisesti. Jo haetut hakusanat eivät kuluta kiintiötä. |
Kun raja ylittyy, API palauttaa koodin 429 ja otsakkeen Retry-After. Jokaisessa vastauksessa on otsakkeet X-RateLimit-Limit / Remaining / Reset ja X-Daily-Limit / X-Daily-Remaining.
| HTTP | code | Merkitys |
|---|---|---|
| 400 | invalid_query / invalid_lang / invalid_country / invalid_group / source_not_offered | Virheellinen parametri (myös source, jota ei tarjota kyseisellä kielellä) |
| 401 | invalid_api_key | Avain puuttuu tai on virheellinen |
| 404 | not_found | Virheellinen source tai polku |
| 429 | rate_limited / daily_quota_exceeded / new_keyword_quota_exceeded | Raja ylitetty (katso Retry-After) |
| 502 | upstream_failed | Haku epäonnistui (voit yrittää uudelleen tunnin kuluttua) |
| 503 | queue_full | Ruuhkaa (katso Retry-After) |
Jos tarvitset korkeampia rajoja tai haluat käyttää palvelua kaupallisesti tai ilmoittaa viasta, ota yhteyttä suoraan ylläpitäjään (Yuki Nakazawa) Telegramissa tai yksityisviestillä X:ssä. Vastaamme japaniksi ja englanniksi.
Käyttöehdot (englanniksi) · Tietosuojakäytäntö (englanniksi)