Một API theo dõi thứ hạng không phải là một thứ duy nhất. Lập trình viên tìm "rank tracking API" thường muốn một endpoint trả về thứ hạng, còn thị trường thì đáp lại bằng danh sách nhà cung cấp. Câu trả lời trung thực là: bạn cần hai nguồn, và chúng trả lời hai câu hỏi khác nhau.
Search Console API miễn phí, chính thức và mãi mãi giới hạn trong những property bạn xác minh được. Một SERP API thì có phí, không chính thức và kiểm tra được bất kỳ từ khóa nào ở bất kỳ đâu, kể cả những từ bạn chưa từng xếp hạng. Riêng mỗi thứ đều không phải công cụ theo dõi thứ hạng. Ghép lại, chúng là khoảng 120 dòng Python và một dòng cron.
Đây là cách lắp. Nó giả định bạn chạy được một script và lưu được một tệp. Nó không giả định bạn muốn làm ra một sản phẩm.
Cuối cùng bạn sẽ có gì
Dành cho ai: lập trình viên hoặc marketer kỹ thuật đã có quyền truy cập Search Console và muốn có thứ hạng theo lịch, không phải trả tiền theo ghế.
Khi xong bạn sẽ có: hai hàm lấy dữ liệu đang chạy, một tệp kết quả hợp nhất mỗi lần chạy, và một quy tắc so sánh không để con số nói dối bạn.
Thời gian: khoảng 90 phút cho lần lắp đầu tiên, sau đó chừng 10 phút rà soát mỗi lần chạy.
Khi hoàn tất trông ra sao: một tệp JSON có ngày tháng chứa thứ hạng của bạn theo truy vấn và thiết bị, kèm ảnh chụp SERP tươi cho bộ từ khóa đã đóng băng, và một diff ngắn so với lần chạy trước.
Trước khi bắt đầu: mỗi nguồn làm được gì và không làm được gì
Phân chia đúng chỗ này thì phần lắp còn lại chỉ là thao tác. Phân chia sai thì bạn mất một tháng cho thứ hoặc vô dụng hoặc đắt đỏ.
Search Console API | SERP API | |
|---|---|---|
Thứ hạng của ai | Chỉ property bạn đã xác minh | Bất kỳ ai, kể cả đối thủ |
Từ khóa | Truy vấn mà bạn đã hiển thị | Bất kỳ từ khóa nào bạn gõ |
Chi phí | Miễn phí | Tính phí theo request |
Tách theo thiết bị | Có, như một dimension | Có, theo từng request |
Vị trí | Quốc gia nơi bạn xếp hạng | Mọi vị trí nhà cung cấp hỗ trợ |
Loại dữ liệu | Click, impression, vị trí tổng hợp | Trang kết quả tại một thời điểm |
Độ sâu lịch sử | Khoảng bạn yêu cầu | Chỉ từ ngày bạn bắt đầu lưu |
Tính chính thức | Dữ liệu của chính Google | Bên thứ ba đọc một trang công khai |
Hai nguồn sẽ lệch nhau, và sự lệch đó là thông tin, không phải lỗi. Search Console lấy trung bình mọi impression trong cả khoảng ngày và trên mọi thiết bị. Một lần lấy SERP là một trang kết quả ở một thời điểm. So sánh thẳng hai thứ thì bạn sẽ đuổi theo những cú tụt ma. Đó là lý do bước thứ năm định nghĩa một quy tắc so sánh.
Ba con số nên biết trước khi viết code. Search Console API nhận giới hạn từ 1 đến 25.000 dòng mỗi request và mặc định là 1.000, nên một site cỡ vừa lấy được ba tháng dữ liệu truy vấn và thiết bị trong một lần gọi. Nó cho phép 1.200 truy vấn mỗi phút cho mỗi site và mỗi người dùng. Và nó áp hạn mức tải đo theo khối mười phút, nơi một khoảng ngày dài tốn hơn khoảng ngắn — đúng lý do hướng dẫn của chính Google nói nên tránh truy vấn lại cùng một dữ liệu.
Hai nguồn, một kết quả. Search Console trả lời "tôi đang hiển thị ở đâu", SERP API trả lời "trang trông thế nào".
Bước 1: đóng băng bộ từ khóa trước khi viết code
Một công cụ theo dõi kéo danh sách từ khóa khác nhau mỗi lần chạy thì không thể trả lời liệu có gì đã thay đổi. Hãy chọn danh sách trước và giữ nguyên nó một quý.
Có ba nhóm, và chúng đến từ những nơi khác nhau.
- Từ Search Console: mọi truy vấn có ít nhất 20 impression trong 90 ngày qua. Bạn không chọn chúng; impression của bạn chọn. Đây là nhóm mà biến động có ý nghĩa, vì phía sau đã có nhu cầu.
- Từ kinh doanh: mười đến hai mươi truy vấn gắn với doanh thu, bất kể bạn có xếp hạng hay không.
- Từ đối thủ: những truy vấn mà một đối thủ xếp hạng còn bạn thì không. Những cái này cần một SERP API, vì Search Console sẽ không bao giờ cho thấy chúng.
Viết danh sách ra một tệp, đánh phiên bản cho nó, và coi việc thêm vào là một thay đổi có chủ đích chứ không phải trôi dạt.
Bước 2: lấy thứ hạng của chính bạn miễn phí
Nửa này là chính thức, miễn phí, và cho bạn phần tách theo thiết bị cùng dữ liệu click mà không SERP API nào có.
from google.oauth2 import service_account
from googleapiclient.discovery import build
service = build(
"searchconsole", "v1",
credentials=service_account.Credentials.from_service_account_file(
"gsc-key.json",
scopes=["https://www.googleapis.com/auth/webmasters.readonly"],
),
)
body = {
"startDate": "2026-06-14",
"endDate": "2026-09-11",
"dimensions": ["query", "device"],
"type": "web",
"dataState": "final",
"rowLimit": 25000,
}
rows = service.searchanalytics().query(
siteUrl="sc-domain:example.com", body=body
).execute().get("rows", [])Hai chi tiết trong request này làm gần hết công việc.
dataState: "final" loại bỏ dữ liệu tươi mà Google còn có thể sửa. Không có nó, hai ba ngày gần nhất nhảy giữa các lần chạy và diff của bạn hiển thị những biến động chưa từng xảy ra.
dimensions: ["query", "device"] là thứ khiến kết quả hữu dụng về sau. Thêm thiết bị ngay bây giờ không tốn gì. Kéo lại ba tháng lịch sử sau đó tốn trọn một lần chạy và không cho bạn gì cho những ngày đã bỏ qua.
Kết quả mong đợi: một dòng cho mỗi truy vấn và thiết bị, kèm click, impression, CTR và vị trí trung bình.
Kiểm tra chất lượng: số dòng phải dưới 25.000. Nếu đúng 25.000 thì bạn đã bị cắt và cần lần gọi thứ hai với startRow: 25000.
Nếu thất bại: lỗi 403 thường nghĩa là email của service account chưa từng được thêm làm người dùng trên property. Hãy thêm trong Search Console, đợi vài phút rồi thử lại.
Bước 3: lấy những SERP bạn không thấy trong dữ liệu của mình
Nửa còn lại bao phủ mọi thứ Search Console không thể làm về mặt cấu trúc. Đây là lần gọi nhỏ nhất chạy được.
import base64, json, urllib.request
LOGIN, PASSWORD = "your-login", "your-password"
def serp(keyword, depth=100):
token = base64.b64encode(f"{LOGIN}:{PASSWORD}".encode()).decode()
payload = json.dumps([{
"keyword": keyword,
"location_name": "United States",
"language_name": "English",
"depth": depth,
}]).encode()
request = urllib.request.Request(
"https://api.dataforseo.com/v3/serp/google/organic/live/advanced",
data=payload,
headers={"Authorization": f"Basic {token}",
"Content-Type": "application/json"},
method="POST",
)
return json.loads(urllib.request.urlopen(request, timeout=120).read())Đặt `depth` là 100, không phải 200. Chúng tôi kiểm tra điều này vào tháng 9 năm 2026 bằng cách yêu cầu 200 kết quả cho sáu truy vấn. Google trả về từ 83 đến 128 kết quả organic rồi dừng, và thứ hạng sâu nhất trong toàn bộ phép thử là 142. Toàn bộ phép thử ở đây. Yêu cầu 200 không cho bạn 200 kết quả, và tùy nhà cung cấp, độ sâu bạn yêu cầu vẫn có thể bị tính tiền. Hãy yêu cầu 100 — bạn gần như luôn nhận được mọi thứ đang tồn tại.
Yêu cầu 200 kết quả và nhận 83 đến 128. Độ sâu trên khoảng 140 không mua được gì ở hầu hết truy vấn thương mại.
Kết quả mong đợi: một payload JSON chứa các mục organic với vị trí, URL, tiêu đề và tên miền.
Kiểm tra chất lượng: xác nhận payload có chứa loại mục ai_overview khi nó xuất hiện. Chỉ trích các mục organic thì bạn sẽ bỏ lỡ lý do một trang mất click dù vẫn giữ thứ hạng.
Nếu thất bại: 401 là lỗi base64 hoặc lỗi thông tin đăng nhập. Mã kiểu 40200 nghĩa là số dư tài khoản đã cạn, và đây là kiểu hỏng phổ biến nhất trong tháng đầu.
Bước 4: lưu payload thô, không lưu bản tóm tắt
Đây là quyết định mà người ta hối tiếc vì đã bỏ qua.
Lưu một bảng thứ hạng thì ổn cho tới khi bạn cần hỏi một câu chưa lường trước: trang kết quả có dài ra không, video có chiếm hết không, có đối thủ mới chen vào không, có AI Overview xuất hiện phía trên màn hình đầu không. Một bản tóm tắt không trả lời được. Payload thô thì trả lời được, với chi phí thêm bằng không.
Cách làm thực tế: ghi một tệp cho mỗi lần chạy, đặt tên theo ngày và giờ, chứa kết quả đã hợp nhất. Giữ 90 ngày gần nhất. Như vậy đủ nhỏ để nằm trong một repo và đủ đầy đủ để trả lời lại những câu hỏi cũ.
Bước 5: viết quy tắc so sánh trước khi lên lịch bất cứ thứ gì
Một công cụ so sánh lần chạy trước với lần này sẽ báo động giả phần lớn số ngày. Số liệu của chính chúng tôi cho thấy vì sao: trên 124 truy vấn có ít nhất 30 impression, truy vấn trung bình dịch 4,57 vị trí từ ngày này sang ngày khác. Tụt bốn bậc là chuyện thứ Ba.
Nên quy tắc cần một ngưỡng và một hướng.
Chỉ báo về một truy vấn khi:
- mức thay đổi vị trí tuyệt đối so với lần chạy trước từ 5 trở lên, VÀ
- truy vấn có ít nhất 20 impression trong cửa sổ so sánh, VÀ
- thay đổi không được giải thích bởi dịch chuyển tỷ lệ thiết bị
Nhóm kết quả theo lớp truy vấn: money, comparison, brand, informational.
Không đề xuất cách sửa.Điều khoản về thiết bị không phải để trang trí. Cùng một truy vấn có thể đứng lệch nhau 11 bậc giữa di động và máy tính, và nếu tỷ lệ thiết bị dịch giữa các lần chạy thì con số trộn cũng dịch theo. Chúng tôi đo riêng điều này và mức đó đủ lớn để bịa ra một xu hướng.
Tốn bao nhiêu
Giá nhà cung cấp thay đổi, nên hãy dựng mô hình thay vì chạy theo báo giá.
- Một từ khóa kiểm tra mỗi ngày trong 30 ngày là 30 request một tháng.
- Một bộ 200 từ khóa kiểm tra hằng ngày là 6.000 request một tháng.
- Cùng bộ đó kiểm tra hằng tuần là khoảng 860 request một tháng.
- Nửa Search Console thì miễn phí và là một request cho mỗi lần xem, bất kể có bao nhiêu từ khóa bên trong.
Toàn bộ quyết định nằm ở phép nhân đó. Câu hỏi "có nên mua công cụ không" gần như luôn quy về nó: đếm request mỗi tháng, nhân với đơn giá mỗi request của bạn, rồi so với giấy phép theo ghế. Theo dõi hằng ngày một bộ từ khóa lớn thường rẻ hơn dưới dạng thuê bao. Theo dõi hằng tuần một bộ nhỏ thường rẻ hơn qua API. Hãy theo dõi một danh sách đã đóng băng thì phía API sẽ vẫn nhỏ.
Khi nào nên mua thay vì tự làm
Hãy tự làm nếu bạn muốn thứ hạng ngay trong pipeline của mình, nếu bạn đã có thông tin đăng nhập SERP API, hoặc nếu bạn cần trang kết quả thô vì lý do khác ngoài thứ hạng.
Hãy mua thay vào đó nếu bạn cần thứ hạng lịch sử trước hôm nay, nếu bạn cần mười vị trí và năm thiết bị cho cùng những từ khóa đó, hoặc nếu không ai trong nhóm sẽ duy trì cron. Danh sách nhà cung cấp đáng đọc chính vì lý do này, và việc sở hữu một hạ tầng dừng lại khi người dựng nó chuyển nhóm là một cái giá thật.
Nếu thứ bạn thực sự cần là một báo cáo tuần viết ra chứ không phải tệp JSON, thì quy trình báo cáo trong Codex bắt đầu từ đúng hai nguồn đó và kết thúc ở một tài liệu. Để đặt cảnh báo lên trên tệp, hướng dẫn thiết kế giám sát đi qua các ngưỡng.
Góc nhìn Auspia: câu hỏi về API theo dõi thứ hạng thực ra là câu hỏi về quyền sở hữu dữ liệu. Search Console cho bạn dữ liệu chính thức về property của mình miễn phí và sẽ luôn như vậy. Mọi thứ còn lại là một ảnh chụp bạn trả tiền. Hãy dựng nửa miễn phí trước, và chỉ thêm nửa có phí ở nơi nó trả lời một câu hỏi bạn thật sự có.
Câu hỏi thường gặp
Google có cung cấp API theo dõi thứ hạng không? Không có bản công khai. Search Console API trả về vị trí trung bình của bạn cho những truy vấn bạn đã hiển thị; gần giống nhưng không phải cùng một thứ. Nó không kiểm tra được một từ khóa bạn chưa xếp hạng, và không kiểm tra được đối thủ.
Một SERP API đi sâu được đến đâu? Nhà cung cấp sẽ nhận mức depth cao hơn 200 rất nhiều, nhưng Google ngừng trả kết quả ở đâu đó giữa 100 và 140 với hầu hết truy vấn thương mại. Yêu cầu nhiều hơn không tạo ra nhiều kết quả hơn.
Nên kiểm tra hằng ngày hay hằng tuần? Hằng tuần cho một bộ từ khóa thông thường. Hằng ngày chỉ cho một danh sách ngắn các truy vấn ra tiền. Kiểm tra hằng ngày một bộ lớn nhân chi phí lên bảy lần và phần lớn là đo nhiễu, vì mức dịch chuyển trung bình mỗi ngày trong dữ liệu của chúng tôi là 4,57 vị trí.
Vì sao con số từ API khác với công cụ theo dõi thứ hạng của tôi? Thiết bị khác, vị trí khác, thời điểm khác và thường là nguồn dữ liệu khác. Con số là một mẫu. Hãy cố định vị trí và thiết bị trong request rồi lấy lại, trước khi kết luận là có gì đã thay đổi.
Một agent có thể chạy việc này thay tôi không? Có, và nó hợp ở chỗ công việc có cùng một hình dạng trong mọi lần chạy. Bức tranh rộng hơn về những gì một agent có thể đảm nhận trong công việc thứ hạng nằm ở hướng dẫn thực hành về agent SEO. Hãy giữ quy tắc so sánh trong một tệp chỉ dẫn bằng văn bản và để agent tạo ra diff; còn quyết định làm hay mua thì để cho con người.
Tác giả: Rowan Blake, chuyên viên phân tích tự động hóa nội dung tại Auspia, phụ trách hơn 100 pipeline xuất bản. Anh viết về pipeline dữ liệu tự động, báo cáo theo lịch và chi phí duy trì những hệ thống chạy mà không cần bạn.
