SERP API
Tìm từ khoá trên Google bằng trình duyệt thật và nhận vị trí của domain cùng toàn bộ kết quả tự nhiên, dạng JSON. Mỗi lần tìm tính một lượt trong gói của bạn.
Xác thực
Tạo key trong ứng dụng › API (gói có SERP API) và gửi trong header của mọi lệnh gọi:
Authorization: Bearer sv_…
Địa chỉ gốc: https://serpvn.example. Nội dung gửi và nhận là JSON (UTF-8).
POST /v1/search
Tìm một từ khoá trên Google, được ưu tiên lên đầu hàng đợi. Với wait, chờ kết quả tới bấy nhiêu giây; xong kịp thì trả về kết quả (200), không thì trả về id (202) để hỏi lại.
| Tham số | Kiểu | Ý nghĩa |
|---|---|---|
keyword | string | Từ khoá cần tìm (bắt buộc) |
domain | string | Domain hoặc URL cần biết vị trí, vd. shop.vn hoặc shop.vn/blog |
subdomains | boolean | Tính cả subdomain (blog.shop.vn) |
country | string | Quốc gia của Google (gl), vd. vn, us |
language | string | Ngôn ngữ giao diện (hl), vd. vi, en |
pages | integer | Số trang kết quả đọc, 1 tới giới hạn của gói (mặc định 1) |
wait | integer | Giây chờ kết quả, 0 tới 120 (mặc định 0: trả id ngay) |
curl -X POST https://serpvn.example/v1/search \
-H "Authorization: Bearer sv_…" \
-H "Content-Type: application/json" \
-d '{"keyword":"giày chạy bộ","domain":"shop.vn","country":"vn","language":"vi","wait":60}'GET /v1/search/{id}
Trạng thái của một lần tìm (queued, running, done, failed, cancelled) và kết quả khi xong.
curl https://serpvn.example/v1/search/9183 -H "Authorization: Bearer sv_…"
GET /v1/keywords
Các từ khoá bạn đã tìm, mới nhất trước: vị trí gần nhất, trước đó, tốt nhất, xu hướng 12 lần gần nhất.
| Tham số | Kiểu | Ý nghĩa |
|---|---|---|
query | string | Lọc theo từ khoá hoặc domain |
limit | integer | Tối đa (mặc định 100) |
curl "https://serpvn.example/v1/keywords?query=giày" -H "Authorization: Bearer sv_…"
GET /v1/keywords/{id}/history
Các lần kiểm tra của một từ khoá, mới nhất trước; full=1 kèm toàn bộ kết quả.
| Tham số | Kiểu | Ý nghĩa |
|---|---|---|
full | boolean | Kèm danh sách kết quả |
limit | integer | Tối đa (mặc định 50) |
curl "https://serpvn.example/v1/keywords/12/history?full=1&limit=10" -H "Authorization: Bearer sv_…"
GET /v1/projects
Các project và tóm tắt: số từ khoá trong top 3/10/30, vị trí trung bình, lên/xuống, lần kiểm tra gần nhất.
curl https://serpvn.example/v1/projects -H "Authorization: Bearer sv_…"
GET /v1/projects/{id}
Một project và từng từ khoá: vị trí, trước đó, tốt nhất, URL, xu hướng; mặc định theo thứ tự đã nhập. counts đếm từng bộ lọc trên mọi từ khoá.
| Tham số | Kiểu | Ý nghĩa |
|---|---|---|
order | string | input (mặc định: thứ tự nhập), rank, change, best, keyword |
dir | string | desc: đảo thứ tự |
top | string | 1, 3, 5, 10, 30, 100: hạng từ 1 tới số đó; na: không thấy |
found | string | yes: domain có trong kết quả; no: không có |
state | string | done, waiting, failed: trạng thái lần kiểm tra gần nhất |
move | string | up, down, same: so với lần trước |
q | string | Chữ trong từ khoá hoặc URL |
curl "https://serpvn.example/v1/projects/3?top=10&order=rank" -H "Authorization: Bearer sv_…"
POST /v1/projects/{id}/stop
Dừng ngay lần kiểm tra đang chạy: các từ khoá chưa tìm được để riêng (run.stopped), kết quả đã có vẫn giữ; từ khoá đang tìm dở tìm xong rồi dừng. Lượt chưa tìm không bị tính.
curl -X POST https://serpvn.example/v1/projects/3/stop -H "Authorization: Bearer sv_…"
POST /v1/projects/{id}/resume
Tiếp tục lần kiểm tra đã dừng: các từ khoá đã dừng chờ tìm lại, trong cùng lần kiểm tra (tính lượt tìm).
curl -X POST https://serpvn.example/v1/projects/3/resume -H "Authorization: Bearer sv_…"
GET /v1/usage
Gói và số lượt tìm đã dùng, còn lại trong tháng.
curl https://serpvn.example/v1/usage -H "Authorization: Bearer sv_…"
Lỗi
Lỗi trả về { "error": "…", "code": "…" }: error để đọc, code để máy xử lý.
| code | HTTP | Khi nào |
|---|---|---|
UNAUTHORIZED | 401 | Thiếu hoặc sai key |
NO_API | 403 | Gói chưa có SERP API |
INVALID | 400 | Tham số sai (lý do trong error) |
NOT_FOUND | 404 | Không có lần tìm, từ khoá hay project này |
QUOTA_EXCEEDED | 429 | Hết lượt tìm của tháng |
RATE_LIMITED | 429 | Gọi quá dày, thử lại sau |