Google, Bing, YouTube, Amazon, Rakuten Ichiba, Yahoo! ve DuckDuckGo'nun arama önerilerini Japonca kana hece alfabesi (あ–ん), A–Z ve 0–9 genişletmeleriyle birlikte döndüren bir JSON API'dir. Şu anda ücretsizdir.
API anahtarı gereklidir. Giriş yaptıktan sonra kullanıcı menüsündeki “API” bölümünden anahtar oluşturabilirsiniz. Anahtarı her istekte gönderin.
Authorization: Bearer gsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Anahtarı yalnızca sunucu tarafında kullanın. Tarayıcıdaki JavaScript'e gömerseniz başkaları da kullanabilir.
{source} yerine aşağıdaki değerlerden birini yazın.
| source | Döndürülen |
|---|---|
google | Google önerileri |
bing | Bing önerileri |
youtube | YouTube önerileri |
amazon | Amazon.co.jp önerileri |
rakuten | Rakuten Ichiba (Japonya) önerileri |
yahoo | Yahoo! arama önerileri |
duckduckgo | DuckDuckGo önerileri (lang=ja Japonya'ya yönelik öneriler döndürür) |
| Parametre | Açıklama |
|---|---|
q (zorunlu) | Anahtar kelime (1–60 karakter). Tam genişlik/yarım genişlik karakterler, büyük/küçük harfler ve boşluklar normalleştirilir. |
lang | ja (varsayılan) / en. en seçildiğinde Japonca kana genişletmesi yapılmaz. |
group | all (varsayılan) veya itself,nihongo,alphabet,number değerlerinin virgülle ayrılmış listesi. |
flat | 1 verildiğinde tekrarları kaldırılmış tek bir suggestions dizisi döndürür. |
Önbellekte olmayan bir anahtar kelimeyi almak onlarca saniye sürdüğü için API önce 202 döndürür ve isteği kuyruğa alır. retry_after_seconds sonra aynı isteği tekrar gönderin; veriler hazırsa sonuçlarla birlikte 200 alırsınız. Sonuçlar 7 gün boyunca önbellekte tutulur. Süre dolduktan sonra, veriler yenilenirken eski veriler "stale": true ile döndürülür. Önbellek her source, q ve lang birleşimi için ayrıdır.
curl -H "Authorization: Bearer $KEY" \ "https://gstudio1.com/api/v1/google/suggest?q=%E3%83%A9%E3%83%B3%E3%83%8B%E3%83%B3%E3%82%B0&flat=1" curl -H "Authorization: Bearer $KEY" \ "https://gstudio1.com/api/v1/rakuten/suggest?q=%E3%83%A9%E3%83%B3%E3%83%8B%E3%83%B3%E3%82%B0&flat=1"
// 202 (kuyrukta)
{ "ok": true, "status": "queued", "source": "google", "queue_position": 3, "retry_after_seconds": 24, ... }
// 200 (hazır)
{ "ok": true, "status": "ready", "query": "ランニング", "source": "google", "fetched_at": "2026-09-19T01:02:03Z",
"stale": false, "count": 412, "suggestions": ["ランニング シューズ", "..."] }
GET /api/v1/usage — Anahtarınızın son 30 günlük kullanımı ve plan limitleri (kimlik doğrulama gerekir)GET /api/v1/status — Kuyruk derinliği ve worker durumu (kimlik doğrulama gerekmez)| Öğe | Limit |
|---|---|
| İstek/dakika | 30 |
| İstek/gün (UTC) | 1,000 |
| Yeni (önbellekte olmayan) anahtar kelime/gün | 20 Her source için ayrı sayılır. Önbellekte olan anahtar kelimeler sayılmaz. |
Bir limit aşıldığında API, Retry-After ile birlikte 429 döndürür. Her yanıtta X-RateLimit-Limit / Remaining / Reset ve X-Daily-Limit / X-Daily-Remaining başlıkları bulunur.
| HTTP | code | Anlamı |
|---|---|---|
| 400 | invalid_query / invalid_lang / invalid_group | Geçersiz parametre |
| 401 | invalid_api_key | Anahtar eksik veya geçersiz |
| 404 | not_found | Geçersiz source veya yol |
| 429 | rate_limited / daily_quota_exceeded / new_keyword_quota_exceeded | Limit aşıldı (Retry-After başlığına bakın) |
| 502 | upstream_failed | Veri alınamadı (bir saat sonra tekrar deneyebilirsiniz) |
| 503 | queue_full | Sistem yoğun (Retry-After başlığına bakın) |