Suggest API v1

Une API JSON qui renvoie, avec extensions, les suggestions de saisie semi-automatique de Google, Bing, YouTube, Amazon, Rakuten Ichiba, Yahoo!, DuckDuckGo, Baidu, Yandex, Naver et Daum dans les 20 langues du site. Le japonais est étendu par les syllabes kana (あ–ん), A–Z et 0–9 ; les autres langues par un espace suivi des lettres propres à la langue, A–Z et 0–9. Vous pouvez commencer avec l’offre gratuite (tarifs).

Authentification

Une clé API est requise. Connectez-vous, puis générez une clé depuis « API » dans le menu utilisateur. Envoyez-la avec chaque requête.

Authorization: Bearer gsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Utilisez la clé uniquement côté serveur. Si vous l’intégrez dans du JavaScript exécuté par le navigateur, des tiers pourront l’utiliser.

GET /api/v1/{source}/suggest

Remplacez {source} par l’une des valeurs suivantes.

source	Renvoie
`google`	Suggestions Google
`bing`	Suggestions Bing
`youtube`	Suggestions YouTube
`amazon`	Suggestions Amazon (`ja` : Amazon.co.jp ; autres langues : la principale boutique de cette langue)
`rakuten`	Suggestions de Rakuten Ichiba (Japon)
`yahoo`	Suggestions de la recherche Yahoo!
`duckduckgo`	Suggestions DuckDuckGo (`lang=ja` renvoie des suggestions pour le Japon)
`baidu`	Suggestions Baidu (`zh`, `zh-tw`, `ja`, `en`)
`yandex`	Suggestions Yandex (`ru`, `uk`, `tr`)
`naver`	Suggestions Naver (`ko`)
`daum`	Suggestions Daum (`ko`)

Paramètre	Description
`q` (obligatoire)	Mot-clé (1 à 60 caractères). Les caractères pleine et demi-chasse, la casse et les espaces sont normalisés.
`lang`	`ja` (par défaut), `en`, `ru`, `ko`, `zh` et les autres codes de langue du site (20 au total). `ja` ajoute l’extension par les kana (`nihongo`) ; les autres langues un espace suivi de leurs propres lettres (`native`). `en` n’a ni l’une ni l’autre.
`group`	`all` (par défaut) ou une liste séparée par des virgules parmi `itself,nihongo,native,alphabet,number`.
`flat`	Avec `1`, l’API renvoie un seul tableau `suggestions` sans doublons.

Fonctionnement asynchrone

La récupération d’un mot-clé qui n’est pas encore en cache prend plusieurs dizaines de secondes : l’API renvoie donc d’abord 202 et le place en file d’attente. Renvoyez la même requête après retry_after_seconds ; une fois les données prêtes, vous recevez 200 avec les résultats. Les résultats sont mis en cache pendant 7 jours. Après expiration, les anciennes données sont renvoyées avec "stale": true pendant leur actualisation. Le cache est distinct pour chaque combinaison de source, q et 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 (en file d’attente)
{ "ok": true, "status": "queued", "source": "google", "queue_position": 3, "retry_after_seconds": 24, ... }

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

Autres points de terminaison

GET /api/v1/usage — Utilisation de votre clé sur les 30 derniers jours et limites de votre offre (authentification requise)
GET /api/v1/status — Longueur de la file d’attente et état des workers (sans authentification)

Limites (offre gratuite)

Élément	Limite
Requêtes par minute	30
Requêtes par jour (UTC)	1,000
Nouveaux mots-clés (hors cache) par jour	20 Compté par source. Les mots-clés déjà en cache ne sont pas décomptés.

En cas de dépassement, l’API renvoie 429 avec Retry-After. Chaque réponse inclut X-RateLimit-Limit / Remaining / Reset et X-Daily-Limit / X-Daily-Remaining.

Erreurs

HTTP	code	Signification
400	invalid_query / invalid_lang / invalid_group	Paramètre invalide (y compris un `source` non proposé pour cette langue)
401	invalid_api_key	Clé manquante ou invalide
404	not_found	`source` ou chemin invalide
429	rate_limited / daily_quota_exceeded / new_keyword_quota_exceeded	Limite dépassée (voir `Retry-After`)
502	upstream_failed	Échec de la récupération (nouvel essai possible après une heure)
503	queue_full	Service surchargé (voir `Retry-After`)

Avant d’utiliser l’API

Les limites de l’offre gratuite peuvent changer sans préavis. Pour les offres payantes, consultez la page des tarifs.
Les données reposent sur les réponses de suggestion publiques de chaque service. Leur exactitude et leur continuité (SLA) ne sont pas garanties.

Conditions d'utilisation (English) · Politique de confidentialité (English)