Suggest API v1

API JSON che restituisce, con le espansioni, i suggerimenti di ricerca di Google, Bing, YouTube, Amazon, Rakuten Ichiba, Yahoo!, DuckDuckGo, Baidu, Yandex, Naver e Daum in tutte le 20 lingue del sito. Il giapponese viene espanso con il sillabario kana (あ–ん), A–Z e 0–9; le altre lingue con uno spazio più le lettere proprie della lingua, A–Z e 0–9. Puoi iniziare con il piano gratuito (prezzi).

Autenticazione

Serve una chiave API. Accedi e genera la chiave dalla voce «API» del menu utente. Inviala con ogni richiesta.

Authorization: Bearer gsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Usa la chiave solo lato server. Se la inserisci nel JavaScript del browser, altre persone potranno usarla.

GET /api/v1/{source}/suggest

Sostituisci {source} con uno dei valori seguenti.

source	Restituisce
`google`	Suggerimenti di Google
`bing`	Suggerimenti di Bing
`youtube`	Suggerimenti di YouTube
`amazon`	Suggerimenti di Amazon (`ja`: Amazon.co.jp; altre lingue: il marketplace principale di quella lingua)
`rakuten`	Suggerimenti di Rakuten Ichiba (Giappone)
`yahoo`	Suggerimenti della ricerca Yahoo!
`duckduckgo`	Suggerimenti di DuckDuckGo (con `lang=ja` restituisce suggerimenti per il Giappone)
`baidu`	Suggerimenti di Baidu (`zh`, `zh-tw`, `ja`, `en`)
`yandex`	Suggerimenti di Yandex (`ru`, `uk`, `tr`)
`naver`	Suggerimenti di Naver (`ko`)
`daum`	Suggerimenti di Daum (`ko`)

Parametro	Descrizione
`q` (obbligatorio)	Parola chiave (da 1 a 60 caratteri). Caratteri a larghezza piena e a mezza larghezza, maiuscole/minuscole e spazi vengono normalizzati.
`lang`	`ja` (predefinito), `en`, `ru`, `ko`, `zh` e gli altri codici lingua del sito (20 in tutto). `ja` aggiunge l’espansione con i kana (`nihongo`); le altre lingue uno spazio più le proprie lettere (`native`). `en` non ha né l’una né l’altra.
`group`	`all` (predefinito) oppure un elenco separato da virgole di `itself,nihongo,native,alphabet,number`.
`flat`	Con `1` restituisce un unico array `suggestions` senza duplicati.

Come funziona il flusso asincrono

Recuperare una parola chiave non ancora in cache richiede qualche decina di secondi, quindi l'API risponde prima con 202 e la mette in coda. Invia di nuovo la stessa richiesta dopo retry_after_seconds: quando i dati sono pronti ricevi 200 con i risultati. I risultati restano in cache per 7 giorni. Dopo la scadenza, i dati vecchi vengono restituiti con "stale": true mentre vengono aggiornati. La cache è separata per ogni combinazione di source, q e lang.

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 (in coda)
{ "ok": true, "status": "queued", "source": "google", "queue_position": 3, "retry_after_seconds": 24, ... }

// 200 (pronto)
{ "ok": true, "status": "ready", "query": "ランニング", "source": "google", "fetched_at": "2026-09-19T01:02:03Z",
  "stale": false, "count": 412, "suggestions": ["ランニング シューズ", "..."] }

Altri endpoint

GET /api/v1/usage — Utilizzo della tua chiave negli ultimi 30 giorni e limiti del piano (autenticazione richiesta)
GET /api/v1/status — Lunghezza della coda e stato dei worker (senza autenticazione)

Limiti (piano gratuito)

Voce	Limite
Richieste al minuto	30
Richieste al giorno (UTC)	1,000
Nuove parole chiave (non in cache) al giorno	20 Conteggiate separatamente per ogni source. Le parole chiave già in cache non vengono conteggiate.

Quando un limite viene superato, l'API restituisce 429 con Retry-After. Ogni risposta include X-RateLimit-Limit / Remaining / Reset e X-Daily-Limit / X-Daily-Remaining.

Errori

HTTP	code	Significato
400	invalid_query / invalid_lang / invalid_group	Parametro non valido (incluso un `source` non disponibile per quella lingua)
401	invalid_api_key	Chiave mancante o non valida
404	not_found	`source` o percorso non valido
429	rate_limited / daily_quota_exceeded / new_keyword_quota_exceeded	Limite superato (vedi `Retry-After`)
502	upstream_failed	Recupero non riuscito (puoi riprovare dopo un'ora)
503	queue_full	Servizio occupato (vedi `Retry-After`)

Prima di usare l'API

I limiti del piano gratuito possono cambiare senza preavviso. Per i piani a pagamento consulta la pagina dei prezzi.
I dati si basano sulle risposte pubbliche di suggerimento di ciascun servizio. Accuratezza e continuità (SLA) non sono garantite.

Termini di servizio (English) · Informativa sulla privacy (English)