Làm thế nào để sử dụng Google Search Console API?

Tạo một dự án trong Google Cloud console, bật Google Search Console API, tạo thông tin xác thực OAuth 2.0, rồi đăng nhập bằng tài khoản Google có quyền truy cập vào property. Sau đó, bạn có thể gửi yêu cầu tới bốn tài nguyên: Search Analytics cho lượt nhấp, lượt hiển thị, CTR và vị trí; URL Inspection cho trạng thái lập chỉ mục; Sitemaps; và Sites. Chỉ riêng API key thì không dùng được: mọi lệnh gọi đều cần token OAuth, và hạn mức sẽ giới hạn lượng dữ liệu bạn có thể yêu cầu.

API bao gồm những gì và không bao gồm những gì

Đó là toàn bộ API. Báo cáo Liên kết, Thống kê thu thập dữ liệu, báo cáo Lập chỉ mục trang và báo cáo Core Web Vitals không có endpoint, nên chúng chỉ có trong giao diện Search Console. URL Inspection cho biết nội dung có trong chỉ mục của Google, chứ không phải kết quả kiểm tra trực tiếp trang.

Thiết lập quyền truy cập

1. Trong Google Cloud console, tạo hoặc chọn một dự án.
2. Bật Google Search Console API cho dự án đó.
3. Cấu hình màn hình yêu cầu đồng ý OAuth và tạo OAuth client ID.
4. Yêu cầu một scope: https://www.googleapis.com/auth/webmasters.readonly để đọc, hoặc https://www.googleapis.com/auth/webmasters nếu muốn gửi hoặc xóa sitemap.
5. Đăng nhập bằng tài khoản có quyền trên property. Để đọc dữ liệu hiệu suất, cần có ít nhất quyền đọc; API thấy đúng những gì tài khoản đó thấy.

Truy vấn Search Analytics đầu tiên của bạn

POST https://www.googleapis.com/webmasters/v3/sites/sc-domain%3Aexample.com/searchAnalytics/query
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "startDate": "2026-09-01",
  "endDate": "2026-09-30",
  "dimensions": ["query", "page"],
  "type": "web",
  "rowLimit": 25000,
  "startRow": 0
}

Site được đặt trong đường dẫn và phải mã hóa URL: sc-domain:example.com cho property loại Tên miền, hoặc đúng tiền tố kèm dấu gạch chéo cuối, ví dụ https://www.example.com/, cho property loại tiền tố URL. Các trường quan trọng nhất:

• Ngày được tính bao gồm cả hai đầu và theo Giờ Thái Bình Dương.
• type mặc định là web; các giá trị còn lại là image, video, news, googleNews và discover. Mỗi loại cần một yêu cầu riêng.
• Bộ lọc được đặt trong dimensionFilterGroups, với các toán tử từ equals và contains đến includingRegex và excludingRegex (cú pháp RE2).
• rowLimit có giá trị từ 1 đến 25,000 (mặc định 1,000); dùng startRow để phân trang lấy phần còn lại.
• dataState mặc định là final; all bổ sung các ngày mới, chưa chốt dữ liệu, còn hourly_all dùng cùng chiều hour.

Mỗi dòng trả về gồm keys, clicks, impressions, ctr (từ 0 đến 1) và position, được sắp xếp theo lượt nhấp, trừ khi bạn nhóm theo ngày.

Các giới hạn ảnh hưởng đến mã của bạn

• 50,000 dòng mỗi ngày cho mỗi loại tìm kiếm. Hãy phân trang bằng startRow theo bước 25,000 và dừng khi nhận được phản hồi rỗng. Để lấy được nhiều dữ liệu nhất, hãy truy vấn từng ngày một.
• Hạn mức tải. Nhóm hoặc lọc đồng thời theo cả trang và truy vấn là loại yêu cầu tốn kém nhất, và khoảng thời gian dài tốn nhiều hơn khoảng ngắn. Nếu vượt hạn mức ngắn hạn, Google sẽ yêu cầu bạn chờ 15 phút.
• Tốc độ yêu cầu. 1,200 truy vấn mỗi phút cho mỗi site và mỗi người dùng; 40,000 mỗi phút và 30,000,000 mỗi ngày cho mỗi dự án.
• Hạn mức URL Inspection. 2,000 lượt kiểm tra mỗi ngày và 600 lượt mỗi phút cho mỗi property.
• 16 tháng lịch sử, và dữ liệu thường có sẵn sau khi ngày kết thúc từ hai đến ba ngày.
• Tổng các dòng không khớp với tổng số. Các truy vấn hiếm bị loại khỏi các dòng ở cấp truy vấn, và nhóm theo trang tính lượt hiển thị khác với nhóm theo property, vì vậy hãy lấy tổng từ một yêu cầu không có chiều query.

Các lỗi thường gặp

• Dùng http:// trong khi property là https://, hoặc bỏ dấu gạch chéo cuối, sẽ gây lỗi quyền truy cập dù tài khoản đã có quyền.
• Yêu cầu một URL nằm ngoài property trong URL Inspection sẽ bị từ chối: URL phải thuộc siteUrl mà bạn truyền vào.
• Nhóm một tháng theo truy vấn và trang trong một lệnh gọi chỉ trả về các dòng hàng đầu. Các yêu cầu theo từng ngày trả về nhiều dòng hơn.

AutoPSEO hỗ trợ như thế nào

Nếu bạn không muốn tự duy trì OAuth và phân trang, AutoPSEO kết nối qua đăng nhập Google và cung cấp cùng dữ liệu đó thông qua REST API riêng tại /v1 (kèm tài liệu OpenAPI 3.1) và một máy chủ MCP, được xác thực bằng API key lấy từ Account → API keys. Có sẵn các khóa chỉ đọc, endpoint search analytics trả về tối đa 5,000 dòng mỗi lệnh gọi, và các công cụ URL Inspection trong ứng dụng sẽ tự theo dõi hạn mức 2,000 lượt mỗi ngày của Google cho bạn. Xem MCP và API key. Để lưu giữ dữ liệu quá 16 tháng mà không cần viết pipeline, hãy xem Search Console lưu giữ dữ liệu bao lâu.

Nguồn: Tài liệu tham khảo API, phương thức truy vấn Search Analytics, giới hạn sử dụng, lấy toàn bộ dữ liệu của bạn và hướng dẫn xác thực của Google.