SERP API

Mọi request phải gửi API key trong header X-API-Key. Key có dạng sk_<prefix>_<secret>.

Tạo key tại trang API key. Giá trị đầy đủ chỉ hiện một lần lúc tạo, hãy lưu vào biến môi trường như SERPBEST_API_KEY và không commit vào code.

Tài khoản phải đang dùng gói có quyền truy cập API, nếu không API trả về 403.

1. 1Gửi POST /serp/search với từ khoá. Server chờ một khoảng ngắn; nếu kết quả có sẵn (hoặc lấy từ cache) thì trả luôn với status: "success".
2. 2Nếu status là queued hoặc running, lưu search_id và gọi GET /serp/searches/{search_id} mỗi 2 giây.
3. 3Dừng khi status là success (đọc organic_results) hoặc failed (đọc error).

Body là JSON. Chỉ q là bắt buộc; các tham số còn lại có giá trị mặc định cho thị trường Việt Nam.

Trả về 200 khi đã có kết quả và 202 khi lượt tìm kiếm còn đang xử lý. Luôn kiểm tra trường status thay vì chỉ dựa vào HTTP status.

curl -X POST "https://api.serpbest.com/api/v1/serp/search" \
  -H "X-API-Key: $SERPBEST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q": "dịch vụ seo", "gl": "vn", "hl": "vi", "device": "desktop"}'

Trả về cùng cấu trúc với POST /serp/search. Mỗi lần poll tính vào giới hạn request, nên giữ nhịp khoảng 2 giây. Chỉ key thuộc cùng tài khoản mới đọc được lượt tìm kiếm của mình.

curl "https://api.serpbest.com/api/v1/serp/searches/SEARCH_ID" \
  -H "X-API-Key: $SERPBEST_API_KEY"

Cả hai endpoint trả về cùng một object.

{
  "search_id": "8f2c4b1e9a7d4c3fb0e6a5d2c1b09e87",
  "status": "success",
  "cached": false,
  "deduplicated": false,
  "processing_ms": 2480,
  "search_parameters": {
    "q": "dịch vụ seo",
    "gl": "vn",
    "hl": "vi",
    "device": "desktop"
  },
  "organic_results": [
    {
      "position": 1,
      "link": "https://example.com/dich-vu-seo",
      "domain": "example.com",
      "title": "Dịch vụ SEO tổng thể",
      "snippet": "Tăng thứ hạng từ khoá bền vững…"
    }
  ],
  "error": null
}

Kết quả cho cùng bộ q + gl + hl + device được cache 60 phút. Response từ cache có cached: true và trả về ngay. Gửi no_cache: true khi cần dữ liệu mới nhất.

Nếu cùng lúc có nhiều request giống hệt nhau, chúng được gộp vào một lượt tìm kiếm (deduplicated: true) nên không phải chờ thêm.

Mỗi search_id được giữ 30 phút; sau đó GET trả về 404.

Mỗi tài khoản được tối đa 120 request/phút (cửa sổ trượt 60 giây, tính cả request poll). Khi vượt, API trả 429 kèm header Retry-After.

Lỗi trả về JSON dạng {"detail": "…"}.