API JSON trả về gợi ý tìm kiếm của Google, Bing, YouTube, Amazon, Rakuten Ichiba, Yahoo!, DuckDuckGo, Baidu, Yandex, Naver và Daum, kèm phần mở rộng, bằng cả 20 ngôn ngữ của trang. Tiếng Nhật được mở rộng theo bảng chữ kana (あ–ん), A–Z và 0–9; các ngôn ngữ khác được mở rộng bằng dấu cách cộng chữ cái riêng của ngôn ngữ đó, A–Z và 0–9. Bạn có thể bắt đầu với gói miễn phí (bảng giá).
Bắt buộc phải có khóa API. Sau khi đăng nhập, bạn có thể tạo khóa tại mục “API” trong menu người dùng. Hãy gửi khóa kèm theo mọi yêu cầu.
Authorization: Bearer gsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Chỉ dùng khóa ở phía máy chủ. Nếu nhúng khóa vào JavaScript trên trình duyệt, người khác có thể sử dụng nó.
Thay {source} bằng một trong các giá trị sau.
| source | Trả về |
|---|---|
google | Gợi ý Google |
bing | Gợi ý Bing |
youtube | Gợi ý YouTube |
amazon | Gợi ý Amazon (ja: Amazon.co.jp; ngôn ngữ khác: chợ chính của ngôn ngữ đó) |
rakuten | Gợi ý Rakuten Ichiba (Nhật Bản) |
yahoo | Gợi ý tìm kiếm Yahoo! |
duckduckgo | Gợi ý DuckDuckGo (lang=ja trả về gợi ý dành cho Nhật Bản) |
baidu | Gợi ý Baidu (zh, zh-tw, ja, en) |
yandex | Gợi ý Yandex (ru, uk, tr) |
naver | Gợi ý Naver (ko) |
daum | Gợi ý Daum (ko) |
| Tham số | Mô tả |
|---|---|
q (bắt buộc) | Từ khóa (1–60 ký tự). Ký tự toàn độ rộng/nửa độ rộng, chữ hoa/chữ thường và khoảng trắng sẽ được chuẩn hóa. |
lang | ja (mặc định), en, ru, ko, zh và các mã ngôn ngữ khác của trang (tổng cộng 20). ja thêm phần mở rộng kana (nihongo); các ngôn ngữ khác thêm dấu cách cộng chữ cái riêng (native). en không có cả hai. |
group | all (mặc định) hoặc danh sách phân tách bằng dấu phẩy gồm itself,nihongo,native,alphabet,number. |
flat | 1 trả về một mảng suggestions duy nhất đã loại bỏ trùng lặp. |
Việc lấy một từ khóa chưa có trong bộ nhớ đệm mất vài chục giây, nên trước tiên API trả về 202 và đưa từ khóa vào hàng đợi. Hãy gửi lại cùng một yêu cầu sau retry_after_seconds; khi dữ liệu đã sẵn sàng, bạn sẽ nhận 200 kèm kết quả. Kết quả được lưu trong bộ nhớ đệm 7 ngày. Sau khi hết hạn, dữ liệu cũ vẫn được trả về với "stale": true trong lúc đang làm mới. Bộ nhớ đệm được tách riêng cho từng tổ hợp source, q và 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 (trong hàng đợi)
{ "ok": true, "status": "queued", "source": "google", "queue_position": 3, "retry_after_seconds": 24, ... }
// 200 (sẵn sàng)
{ "ok": true, "status": "ready", "query": "ランニング", "source": "google", "fetched_at": "2026-09-19T01:02:03Z",
"stale": false, "count": 412, "suggestions": ["ランニング シューズ", "..."] }
GET /api/v1/usage — Mức sử dụng khóa của bạn trong 30 ngày qua và giới hạn của gói (cần xác thực)GET /api/v1/status — Độ dài hàng đợi và trạng thái worker (không cần xác thực)| Hạng mục | Giới hạn |
|---|---|
| Yêu cầu/phút | 30 |
| Yêu cầu/ngày (UTC) | 1,000 |
| Từ khóa mới (chưa có trong bộ nhớ đệm)/ngày | 20 Tính riêng cho từng source. Từ khóa đã có trong bộ nhớ đệm không bị tính. |
Khi vượt giới hạn, API trả về 429 kèm Retry-After. Mọi phản hồi đều có X-RateLimit-Limit / Remaining / Reset và X-Daily-Limit / X-Daily-Remaining.
| HTTP | code | Ý nghĩa |
|---|---|---|
| 400 | invalid_query / invalid_lang / invalid_group | Tham số không hợp lệ (bao gồm source không được cung cấp cho ngôn ngữ đó) |
| 401 | invalid_api_key | Thiếu khóa hoặc khóa không hợp lệ |
| 404 | not_found | source hoặc đường dẫn không hợp lệ |
| 429 | rate_limited / daily_quota_exceeded / new_keyword_quota_exceeded | Vượt giới hạn (xem Retry-After) |
| 502 | upstream_failed | Không lấy được dữ liệu (có thể thử lại sau 1 giờ) |
| 503 | queue_full | Hệ thống đang bận (xem Retry-After) |
Điều khoản dịch vụ (English) · Chính sách quyền riêng tư (English)