Suggest API v1

Ένα JSON API που επιστρέφει προτάσεις αναζήτησης (με επέκταση) από Google, Bing, YouTube, Amazon, eBay, Shopee, Rakuten Ichiba, Yahoo!, DuckDuckGo, Baidu, Yandex, Naver και Daum, στις 50 γλώσσες του ιστότοπου. Τα ιαπωνικά επεκτείνονται με τις συλλαβές kana (あ–ん), A–Z και 0–9. Οι άλλες γλώσσες επεκτείνονται με κενό, τα γράμματα της κάθε γλώσσας (για τα ελληνικά Α–Ω), A–Z και 0–9. Μπορείτε να ξεκινήσετε με το δωρεάν πακέτο (τιμές).

Πιστοποίηση

Απαιτείται κλειδί API. Συνδεθείτε και δημιουργήστε ένα κλειδί από το «API» στο μενού χρήστη. Στείλτε το με κάθε αίτημα.

Authorization: Bearer gsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Χρησιμοποιείτε το κλειδί μόνο από τον διακομιστή σας. Αν το ενσωματώσετε σε JavaScript του προγράμματος περιήγησης, μπορούν να το χρησιμοποιήσουν τρίτοι.

GET /api/v1/{source}/suggest

Ορίστε στο {source} μία από τις παρακάτω τιμές.

source	Επιστρέφει
`google`	Προτάσεις αναζήτησης Google
`bing`	Προτάσεις αναζήτησης Bing
`youtube`	Προτάσεις αναζήτησης YouTube
`amazon`	Προτάσεις αναζήτησης Amazon από την αγορά που επιλέγετε με `lang` και `country` (Amazon.com, Amazon.co.uk, Amazon.de, Amazon.co.jp κ.ά.)
`ebay`	Προτάσεις αναζήτησης eBay από τον ιστότοπο που επιλέγετε με `lang` και `country` (ebay.com, ebay.co.uk, ebay.de, ebay.fr κ.ά. · `en`, `de`, `fr`, `it`, `es`, `nl`, `pl`)
`shopee`	Προτάσεις αναζήτησης Shopee από τον ιστότοπο που επιλέγετε με `lang` και `country` (shopee.tw, shopee.sg, shopee.com.my, shopee.ph, shopee.co.id, shopee.vn, shopee.co.th, shopee.com.br κ.ά. · `zh-tw`, `en`, `ms`, `fil`, `id`, `vi`, `th`, `pt`)
`duckduckgo`	Προτάσεις αναζήτησης DuckDuckGo (με `lang=ja` επιστρέφει προτάσεις για την Ιαπωνία)
`baidu`	Προτάσεις αναζήτησης Baidu (`zh`, `ja`, `en`)
`yandex`	Προτάσεις αναζήτησης Yandex (`ru`, `tr`, `kk`, `uz`)
`naver`	Προτάσεις αναζήτησης Naver (`ko`)
`daum`	Προτάσεις αναζήτησης Daum (`ko`)
`yahoo`	Προτάσεις αναζήτησης Yahoo! JAPAN (μόνο Ιαπωνία) · `zh-tw`: Yahoo奇摩 (Yahoo! Ταϊβάν)
`rakuten`	Προτάσεις αναζήτησης Rakuten Ichiba (μόνο Ιαπωνία)

Παράμετρος	Περιγραφή
`q` (υποχρεωτική)	Λέξη-κλειδί (1–60 χαρακτήρες). Οι χαρακτήρες πλήρους/μισού πλάτους, τα πεζά/κεφαλαία και τα κενά κανονικοποιούνται.
`lang`	`ja` (προεπιλογή, διατηρείται για τους υπάρχοντες χρήστες, αλλά συνιστάται να ορίζεται ρητά), `en`, `ru`, `ko`, `zh` και οι υπόλοιποι κωδικοί γλωσσών του ιστότοπου (50 συνολικά). Το `ja` προσθέτει επέκταση με kana (`nihongo`), οι άλλες γλώσσες κενό και τα δικά τους γράμματα (`native`). Το `en` δεν έχει καμία από τις δύο.
`country`	Χώρα / αγορά (προαιρετικό, ISO 3166-1 alpha-2). `en`: us (προεπιλογή), 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 κ.ά. Ισχύει για Amazon (αγορά), Bing, DuckDuckGo, Google και YouTube. Τα Amazon, Bing και DuckDuckGo ακολουθούν πιστά τη χώρα. Τα Google και YouTube προσαρμόζονται επίσης, αλλά μπορεί να επηρεάζονται από την περιοχή από την οποία στέλνεται το αίτημα.
`group`	`all` (προεπιλογή) ή λίστα διαχωρισμένη με κόμματα από `itself,nihongo,native,alphabet,number`.
`flat`	Με `1` επιστρέφεται ένας ενιαίος πίνακας `suggestions` χωρίς διπλότυπα.

Πώς λειτουργεί η ασύγχρονη ροή

Η ανάκτηση μιας λέξης-κλειδιού που δεν έχει ανακτηθεί ακόμη διαρκεί αρκετές δεκάδες δευτερόλεπτα, γι' αυτό το API επιστρέφει πρώτα 202 και τη βάζει σε ουρά. Στείλτε ξανά το ίδιο αίτημα μετά από retry_after_seconds: μόλις τα δεδομένα είναι έτοιμα, λαμβάνετε 200 με τα αποτελέσματα. Τα δεδομένα παραμένουν στην κρυφή μνήμη για 7 ημέρες. Μετά τη λήξη τους, όσο ανανεώνονται, επιστρέφονται τα παλιά δεδομένα με "stale": true. Η κρυφή μνήμη είναι ξεχωριστή για κάθε συνδυασμό source, q και lang.

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 (σε ουρά)
{ "ok": true, "status": "queued", "source": "google", "lang": "en", "country": "us", "queue_position": 3, "retry_after_seconds": 24, ... }

// 200 (έτοιμο)
{ "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", "..."] }

Άλλα endpoints

GET /api/v1/usage — Χρήση του κλειδιού σας τις τελευταίες 30 ημέρες και όρια του πακέτου σας (απαιτείται πιστοποίηση)
GET /api/v1/status — Μήκος ουράς και κατάσταση workers (χωρίς πιστοποίηση)

Όρια (δωρεάν πακέτο)

Στοιχείο	Όριο
Αιτήματα ανά λεπτό	30
Αιτήματα ανά ημέρα (UTC)	1,000
Νέες λέξεις-κλειδιά (εκτός κρυφής μνήμης) ανά ημέρα	20 Μετρώνται ανά source. Οι ήδη ανακτημένες λέξεις-κλειδιά δεν μετρούν.

Όταν ξεπεραστεί ένα όριο, το API επιστρέφει 429 με Retry-After. Κάθε απάντηση περιλαμβάνει X-RateLimit-Limit / Remaining / Reset και X-Daily-Limit / X-Daily-Remaining.

Σφάλματα

HTTP	code	Σημασία
400	invalid_query / invalid_lang / invalid_country / invalid_group / source_not_offered	Μη έγκυρη παράμετρος (και `source` που δεν προσφέρεται για τη συγκεκριμένη γλώσσα)
401	invalid_api_key	Το κλειδί λείπει ή δεν είναι έγκυρο
404	not_found	Μη έγκυρο `source` ή διαδρομή
429	rate_limited / daily_quota_exceeded / new_keyword_quota_exceeded	Υπέρβαση ορίου (δείτε `Retry-After`)
502	upstream_failed	Η ανάκτηση απέτυχε (νέα δοκιμή μετά από μία ώρα)
503	queue_full	Υπερφόρτωση (δείτε `Retry-After`)

Επικοινωνία

Για υψηλότερα όρια, εμπορική χρήση ή αναφορές σφαλμάτων, στείλτε απευθείας μήνυμα στον διαχειριστή (Yuki Nakazawa) μέσω Telegram ή X. Απαντά στα αγγλικά ή στα ιαπωνικά.

Πριν χρησιμοποιήσετε το API

Τα όρια του δωρεάν πακέτου μπορεί να αλλάξουν χωρίς προειδοποίηση. Για τα επί πληρωμή πακέτα δείτε τη σελίδα τιμών.
Τα δεδομένα βασίζονται στις δημόσιες απαντήσεις προτάσεων κάθε υπηρεσίας. Η ακρίβεια και η συνέχεια (SLA) δεν είναι εγγυημένες.

Όροι χρήσης (στα αγγλικά) · Πολιτική απορρήτου (στα αγγλικά)