Tài liệu SERP API

SERP API cho phép bạn lấy dữ liệu kết quả tìm kiếm Google dưới dạng JSON thô, dùng chung hạ tầng cào và cùng đơn giá với SERP Checker. Tài liệu này mô tả đầy đủ cách xác thực, các endpoint, định dạng dữ liệu trả về, webhook và bảng mã lỗi.

1. Quy trình tích hợp#

1. Lấy API key trong app, mục SERP API, tab API Keys.
2. Khai báo Pingback URL và Pingback Token ở cùng tab đó.
3. Gọi POST /serp-api/trigger kèm từ khóa, nhận về snapshot_id.
4. Chờ SERPUPDATE gọi webhook về máy chủ của bạn khi snapshot xong.
5. Gọi GET /serp-api/{snapshot_id} để lấy dữ liệu.

2. Xác thực#

Mọi lượt gọi đều gửi kèm header X-API-KEY. Key là chuỗi 32 ký tự hex thường, không dấu gạch.

curl -X GET https://app.serpupdate.com/api/v1/serp-api/languages 
  -H "X-API-KEY: 3f9a1c7e4b2d48a6915e0c83d7f6b214"

3. Danh sách endpoint#

3.1. Tạo snapshot#

POST /serp-api/trigger

Đây là lệnh gọi tính phí. Mỗi lượt gọi nhận đúng một từ khóa. Trả về snapshot_id ngay lập tức, dữ liệu lấy sau.

Ví dụ lệnh gọi

curl -X POST https://app.serpupdate.com/api/v1/serp-api/trigger 
  -H "X-API-KEY: 3f9a1c7e4b2d48a6915e0c83d7f6b214" 
  -H "Content-Type: application/json" 
  -H "Idempotency-Key: order-8841" 
  -d '{
  "input": [
    {
      "keyword": "sàn nhựa giả gỗ",
      "language": "vi",
      "country": "VN",
      "device": "desktop",
      "start_page": 1,
      "end_page": 10,
      "include_aio": true
    }
  ]
}'

Phản hồi

{ "snapshot_id": "sd_abc123xyz" }

3.2. Chống tính phí trùng#

Gửi kèm header Idempotency-Key (tùy chọn, tối đa 64 ký tự) khi gọi trigger. Nếu mạng lỗi và bạn phải gọi lại cùng một key, hệ thống nhận ra và không chạy thêm một lượt tính phí nữa. Nên dùng một giá trị duy nhất cho mỗi lượt nghiệp vụ, ví dụ mã đơn hàng hoặc UUID.

3.3. Lấy kết quả#

GET /serp-api/{snapshot_id}

curl https://app.serpupdate.com/api/v1/serp-api/sd_abc123xyz 
  -H "X-API-KEY: 3f9a1c7e4b2d48a6915e0c83d7f6b214"

3.4. Tra cứu địa điểm và ngôn ngữ#

GET /serp-api/locations nhận các tham số truy vấn: name (khớp gần đúng), country (ISO-2), page (đánh số từ 0), size.

GET /serp-api/languages không có tham số, trả về toàn bộ danh sách ngôn ngữ Google hỗ trợ.

Dùng hai endpoint này để lấy giá trị hợp lệ cho location và language trước khi gọi trigger.

4. Cấu trúc dữ liệu trả về#

Thân phản hồi là một mảng, mỗi phần tử ứng với một từ khóa. Hiện tại luôn có đúng một phần tử.

[
  {
    "keyword": "best protein powder for muscle gain",
    "organic": [
      {
        "rank": 1,
        "title": "Protein Powders For Muscle Growth Support",
        "url": "https://www.gnc.com/buy/protein-powders-for-muscle-growth",
        "domain": "gnc.com",
        "description": "Whey protein is often chosen for its rapid absorption..."
      }
    ],
    "aio_text": "Nội dung AI Overview dạng markdown, kèm chỉ dẫn nguồn [[1]](https://...)",
    "aio_reference": [
      {
        "rank": 1,
        "url": "https://www.healthline.com/nutrition/best-protein-powder-to-build-muscle",
        "domain": "healthline.com",
        "title": "The 10 Best Protein Powders to Build Muscle",
        "description": "Protein powders, especially when combined with resistance training..."
      }
    ]
  }
]

5. Pingback webhook#

Khi snapshot xong hoặc thất bại, SERPUPDATE gửi một lệnh POST tới URL bạn khai báo. Đây là chiều SERPUPDATE gọi vào máy chủ của bạn, không phải endpoint bạn gọi.

POST https://your-server.com/webhook/serpupdate
User-Agent: SerpUpdate-Webhook/1.0
X-SerpUpdate-Delivery: dlv_a1b2c3d4e5f6
X-SerpUpdate-Token: token bạn đặt ở tab API Keys
Content-Type: application/json

{
  "snapshot_id": "sd_abc123xyz",
  "status": "ready",
  "keyword": "sàn nhựa giả gỗ",
  "collect_time_ms": 18450
}

status nhận giá trị ready khi thành công và failed khi thất bại. Trường collect_time_ms là thời gian thu thập tính bằng mili giây.

Máy chủ của bạn phải trả về mã 2xx. Nếu không, SERPUPDATE thử lại tối đa 3 lần, cách nhau 30 giây, 5 phút và 30 phút.

Ví dụ xử lý webhook bằng Node.js

import express from "express";
const app = express();
app.use(express.json());

app.post("/webhook/serpupdate", (req, res) => {
  if (req.get("X-SerpUpdate-Token") !== process.env.SERPUPDATE_PINGBACK_TOKEN) {
    return res.sendStatus(401);
  }
  const { snapshot_id: id, status } = req.body;
  if (status === "ready") {
    console.log("snapshot ready:", id);
  }
  res.sendStatus(200);
});

Yêu cầu cấu hình#

• Pingback URL bắt buộc dùng https://. Hệ thống chặn các địa chỉ nội bộ như localhost, 127.0.0.1, dải 10.x, 192.168.x, 172.16.x đến 172.31.x.
• Pingback Token dài từ 16 đến 128 ký tự.
• Trong app có nút Test pingback để bắn thử một lượt gọi và xem máy chủ của bạn trả về mã gì.
• Nếu một lần gửi thất bại, bảng Request logs có nút gửi lại thủ công.

6. Bảng mã lỗi#

Vượt hạn mức gọi#

Khi vượt hạn mức, hệ thống trả về HTTP 429 kèm header Retry-After tính bằng giây. Hãy chờ đúng khoảng đó rồi gọi lại thay vì thử liên tục.

7. Vòng đời và giới hạn#

• Thời gian lưu trữ: 30 ngày kể từ lúc snapshot hoàn tất. Sau đó gọi lại sẽ nhận mã 410.
• Cảnh báo sắp hết hạn: bảng Request logs gắn nhãn khi còn dưới 3 ngày.
• Trạng thái snapshot: running, ready, failed, expired.
• Không xóa được snapshot thủ công. Hệ thống tự dọn theo chính sách lưu trữ.
• Số trang: start_page và end_page nằm trong khoảng 1 đến 10.