Cách Xây Dựng Một Trình Theo Dõi Thứ Hạng Với Google Search API Trong Python

TL;DR:

• Trình theo dõi thứ hạng là một pipeline theo thời gian, không phải một yêu cầu SERP. Nó phải duy trì truy vấn, vị trí, ngôn ngữ, thiết bị, miền tìm kiếm, thời gian quan sát, URL xếp hạng và vị trí.
• Sử dụng API Tìm Kiếm khi bạn cần quan sát SERP thô. Sử dụng một nền tảng SEO đầy đủ khi bạn cũng cần phát hiện từ khóa, báo cáo, cảnh báo và quy trình làm việc của khách hàng.
• Chuẩn hóa tên miền trước khi khớp với miền mục tiêu. Xử lý www.example.com, sự khác biệt về cách, đường dẫn, và các miền con theo một chính sách rõ ràng.
• Ghi lại “không xếp hạng” như dữ liệu. Không chuyển đổi sự vắng mặt thành vị trí số không, và không mang vị trí của ngày hôm qua về phía trước.
• Lưu trữ cả URL xếp hạng cũng như thứ hạng. Một miền có thể giữ vị trí của nó trong khi trang đích thay đổi.
• API Tìm Kiếm Google không scrapeless trả về dữ liệu tìm kiếm có cấu trúc. Cài đặt Python bên dưới yêu cầu SERP, phân tích kết quả tự nhiên, và viết các bản sao CSV chỉ thêm.

Những gì một Trình theo dõi Thứ hạng Thực sự Đo lường

Một trình theo dõi thứ hạng quan sát nơi mà một miền mục tiêu xuất hiện trong một tập hợp kết quả tìm kiếm cụ thể tại một thời điểm cụ thể.

Định nghĩa đó là có chủ ý hạn hẹp. Vị trí phụ thuộc vào truy vấn, quốc gia hoặc vị trí, ngôn ngữ, miền Google, thiết bị, loại kết quả, và độ sâu phân trang. Thay đổi một chiều và quan sát thuộc về một chuỗi khác.

Một bản ghi đáng tin cậy nên chứa ít nhất:

• từ khóa
• miền mục tiêu
• vị trí quan sát hoặc trạng thái không xếp hạng rõ ràng
• URL xếp hạng
• tiêu đề kết quả
• cài đặt quốc gia hoặc vị trí
• ngôn ngữ
• thiết bị
• miền Google
• dấu thời gian quan sát

Trình theo dõi không bao giờ nên ngụ ý rằng một SERP được lấy mẫu là một thứ hạng phổ quát. Cá nhân hóa, thí nghiệm, thay đổi chỉ mục, và sự khác biệt khu vực là một phần của tìm kiếm.

API Tìm Kiếm so với Nền tảng theo dõi Thứ hạng

Một API Tìm Kiếm và một nền tảng theo dõi thứ hạng giải quyết các công việc liên quan nhưng khác nhau.

Chọn một API khi các quan sát thứ hạng là một đầu vào cho một sản phẩm nội bộ, thí nghiệm, hoặc kho dữ liệu. Chọn một nền tảng khi các nhà phân tích cần một giao diện sẵn có và quy trình làm việc báo cáo.

Mô hình Yêu cầu API Tìm Kiếm Google

API Tìm Kiếm Google không scrapeless chấp nhận các tham số tìm kiếm và trả về dữ liệu có cấu trúc. Tài liệu API Tìm Kiếm Google hiện tại ghi lại các tham số chung bao gồm truy vấn, quốc gia, ngôn ngữ, miền Google, loại kết quả, độ lệch, và số lượng kết quả.

Sử dụng tên gọi hiện tại của khách hàng, API Tìm Kiếm Google, trong bản sao sản phẩm. Các tên diễn viên và tuyến đường API ổn định có thể giữ tên gọi nội bộ cũ hơn.

Yêu cầu được sử dụng trong hướng dẫn này là một POST đến /api/v1/scraper/request với diễn viên scraper.google.search. Xác thực thuộc về tiêu đề x-api-token. Đầu vào giữ truy vấn và cài đặt tìm kiếm cùng nhau để mọi phản hồi có thể được lần theo cấu hình lấy mẫu của nó.

Xây dựng Trình theo dõi trong Python

Kịch bản bên dưới thực hiện bốn công việc:

1. gửi một yêu cầu API Tìm Kiếm Google cho mỗi từ khóa;
2. tìm kết quả tự nhiên đầu tiên mà tên miền của nó khớp với chính sách mục tiêu;
3. viết một bản sao CSV chỉ thêm;
4. giữ vị trí và URL trống khi mục tiêu không được tìm thấy.

Điều kiện tiên quyết: yêu cầu trực tiếp cần một khóa API Scrapeless trong SCRAPELESS_API_KEY. Logic khớp, chuẩn hóa, và CSV có thể được thử nghiệm cục bộ với một phản hồi đã lưu trước khi thực hiện một yêu cầu xác thực.

import csv
import os
from datetime import datetime, timezone
from pathlib import Path
from urllib.parse import urlparse, urlunsplit

import requests

API_URL = "https://api.scrapeless.com/api/v1/scraper/request"


def normalized_host(value: str) -> str:
    candidate = value if "://" in value else urlunsplit(("https", value, "", "", ""))
    host = (urlparse(candidate).hostname or "").lower().rstrip(".")
    return host.removeprefix("www.")


def host_matches(result_url: str, target_domain: str, include_subdomains=True) -> bool:
    result_host = normalized_host(result_url)
    target_host = normalized_host(target_domain)
    if not result_host or not target_host:
        return False
    return result_host == target_host or (
        include_subdomains and result_host.endswith(f".{target_host}")
    )


def organic_results(payload: dict) -> list[dict]:
    if isinstance(payload.get("organic_results"), list):
        return payload["organic_results"]
    data = payload.get("data", {})
    if isinstance(data, dict) and isinstance(data.get("organic_results"), list):
        return data["organic_results"]
    return []


def find_rank(payload: dict, target_domain: str) -> dict:
    for fallback_position, item in enumerate(organic_results(payload), start=1):
        url = item.get("link") or item.get("url") or ""
        if host_matches(url, target_domain):
            return {
                "position": item.get("position", fallback_position),
                "ranking_url": url,
                "title": item.get("title", ""),
            }
    return {"position": None, "ranking_url": "", "title": ""}


def fetch_serp(keyword: str, *, gl="us", hl="en", device="desktop") -> dict:
    api_key = os.environ["SCRAPELESS_API_KEY"]
    response = requests.post(
        API_URL,
        headers={"x-api-token": api_key, "Content-Type": "application/json"},
        json={
            "actor": "scraper.google.search",
            "input": {
                "q": keyword,
                "gl": gl,
                "hl": hl,
                "google_domain": "google.com",
                "device": device,
                "start": 0,
            },
        },
        timeout=60,
    )
    response.raise_for_status()
    return response.json()


def append_snapshot(path: Path, row: dict) -> None:
    fields = [
        "observed_at", "keyword", "target_domain", "position",
        "ranking_url", "title", "gl", "hl", "device", "google_domain",
    ]
    exists = path.exists()
    with path.open("a", newline="", encoding="utf-8") as handle:
        writer = csv.DictWriter(handle, fieldnames=fields)
        if not exists:
            writer.writeheader()
        writer.writerow(row)


def track(keyword: str, target_domain: str, output="rank_history.csv") -> dict:
    settings = {"gl": "us", "hl": "en", "device": "desktop"}
    payload = fetch_serp(keyword, **settings)
    match = find_rank(payload, target_domain)
    row = {
        "observed_at": datetime.now(timezone.utc).isoformat(),
        "keyword": keyword,
        "target_domain": normalized_host(target_domain),
        "position": match["position"] or "",
        "ranking_url": match["ranking_url"],
        "title": match["title"],
        **settings,
        "google_domain": "google.com",
    }
    append_snapshot(Path(output), row)
    return row


if __name__ == "__main__":
    print(track("web scraping api", "scrapeless.com"))

Thư viện tiêu chuẩn urlparse tài liệu giải thích tại sao phân tích tên miền nên sử dụng một bộ phân tích URL thay vì cắt chuỗi. Kịch bản chỉ loại bỏ một www. đứng đầu và tùy chọn chấp nhận các miền con; điều chỉnh chính sách đó trước khi theo dõi một miền nhiều thương hiệu.

Xác thực Bộ phân tích Vị trí

Trước khi sử dụng tín dụng trực tiếp, lưu một phản hồi API thực từ tài khoản và chạy bộ phân tích chống lại nó. Bao gồm ít nhất những phản hồi mẫu này:

Không tính toán một vị trí từ thứ tự danh sách khi API cung cấp một trường position rõ ràng mà không hiểu rõ về phân trang. Trên một trang kết quả sau, chỉ số danh sách một không phải là vị trí toàn cầu một. Bảo tồn vị trí được cung cấp hoặc thêm độ lệch trang một cách có chủ ý.

Lưu Lịch Sử Mà Không Viết Lại Nó

Các ảnh chụp chỉ thêm là dễ dàng để kiểm tra hơn một bảng "hạng hiện tại" có thể thay đổi. Một chuyển đổi sau đó có thể chọn hàng mới nhất cho mỗi từ khóa và thị trường.

CSV hoạt động cho một tracker cá nhân. Một dịch vụ sản xuất nên sử dụng một khóa cơ sở dữ liệu phân biệt từ khóa, miền, quốc gia hoặc vị trí, ngôn ngữ, thiết bị, miền Google, và thời gian quan sát. Tài liệu SQLite table documentation là đủ cho một dịch vụ cục bộ gọn gàng; một kho dữ liệu trở nên hữu ích khi chuỗi dữ liệu cho các bảng điều khiển và cảnh báo. Đối với các quy tắc định danh URL vượt quá chính sách tên miền được sử dụng ở đây, tham khảo tiêu chuẩn cú pháp chung URI.

Giữ cả position và ranking_url. Những thay đổi này có ý nghĩa khác nhau:

• thay đổi vị trí, URL không thay đổi: cùng một trang đích đã di chuyển;
• vị trí không thay đổi, URL thay đổi: Google đã chọn một trang khác;
• vị trí trống: miền không được tìm thấy trong độ sâu kết quả mẫu;
• nhiều URL từ miền xuất hiện: lưu vị trí tốt nhất và tùy chọn giữ mọi kết quả trong bảng chi tiết.

Xử Lý Địa Lý, Ngôn Ngữ, Thiết Bị, và Thời Gian

Đối xử với các cài đặt tìm kiếm như các chiều, không phải nhãn tùy chọn được thêm sau.

• gl chỉ ra bối cảnh quốc gia.
• hl kiểm soát ngôn ngữ giao diện.
• google_domain chọn thuộc tính Google.
• device tách biệt các quan sát của máy tính để bàn và di động khi được hỗ trợ.
• một cài đặt vị trí chính xác có thể mô hình hóa một thị trường hẹp hơn so với một quốc gia.
• dấu thời gian nên sử dụng UTC trong lưu trữ và chỉ chuyển đổi cho hiển thị.

Không trộn lẫn chuỗi cấp thành phố với chuỗi cấp quốc gia dưới cùng một đường biểu đồ. Tương tự, một kết quả di động không nên thay thế một quan sát trên máy tính để bàn một cách lén lút.

Thời gian mẫu cũng quan trọng. Chạy các nhóm từ khóa tương đương trong một cửa sổ giới hạn. Nếu một lô trải dài nhiều giờ, lưu dấu thời gian của mỗi yêu cầu thay vì một ngày cho toàn bộ công việc.

Tính Toán Chi Phí Mà Không Công Bố Một Giá Cũ

Sự tính toán ổn định có ích hơn một số tiền kế hoạch đã sao chép:

monthly requests = keywords × markets × devices × pages sampled × runs per month

Sau đó áp dụng tỷ lệ tài khoản hiện tại và chính sách quản lý thất bại. Tách biệt các yêu cầu đã lập kế hoạch từ các nỗ lực lặp lại và thất bại để một nhóm vận hành có thể giải thích hóa đơn. Kiểm tra giá Scrapeless tại thời điểm triển khai thay vì nhúng một số có thể lỗi thời trước khi mã lỗi thời.

Bắt Đầu Quét Với Scrapeless

Khởi động quy trình làm việc quét web và tự động hóa của bạn với Scrapeless!
Đăng ký hôm nay và nhận 5 đô la tín dụng miễn phí — không cần thẻ tín dụng.

Nhận tín dụng miễn phí của bạn ngay bây giờ trong Bảng điều khiển Scrapeless.

Danh Sách Kiểm Tra Sản Xuất

• Ghim một hợp đồng sơ đồ cho các trường mà bộ phân tích tiêu thụ.
• Giữ khóa API trong một trình quản lý bí mật hoặc biến môi trường.
• Lặp lại chỉ các yêu cầu bị giới hạn sau khi gặp sự cố tạm thời; không lặp lại vô tận.
• Lưu cài đặt yêu cầu bên cạnh mỗi quan sát.
• Phân biệt không xếp hạng với yêu cầu bị thất bại.
• Theo dõi URL xếp hạng, không chỉ vị trí số.
• Bảo tồn một phản hồi đã redacted cho các bài kiểm tra hồi quy bộ phân tích.
• Tôn trọng các điều khoản, yêu cầu quyền riêng tư, và pháp luật địa phương áp dụng.
• Cảnh báo về việc thiếu các lô và sự trôi dạt sơ đồ trước khi cảnh báo về sự di chuyển SEO.

Kết Luận

Một công cụ theo dõi hạng hữu ích là một hệ thống quan sát có kỷ luật. API Tìm kiếm Google Scrapeless cung cấp các bản ghi SERP có cấu trúc; giá trị đến từ việc khớp chính xác, các chiều tìm kiếm đầy đủ, lịch sử chỉ thêm, và cách xử lý trung thực các kết quả vắng mặt.

Bắt đầu với một từ khóa, một thị trường, một thiết bị, và một phản hồi đã xác minh. Một khi chuỗi đã ổn định, mở rộng lô và kết nối CSV hoặc cơ sở dữ liệu với một bảng điều khiển. Đối với các quy trình công việc liền kề, xem hướng dẫn API Tìm kiếm Google.

Xây Dựng Bản Ảnh SERP Đầu Tiên Của Bạn

Tham gia cộng đồng Scrapeless để được hỗ trợ triển khai và các mẫu pipeline dữ liệu: Discord · Telegram.
Tạo một tài khoản miễn phí tại app.scrapeless.com, chạy một truy vấn có giới hạn, và xác thực phản hồi đã lưu trước khi lên lịch cho trình theo dõi.

Câu hỏi thường gặp

Q: Trình theo dõi xếp hạng API là gì?

Trình theo dõi xếp hạng API cung cấp các quan sát về kết quả tìm kiếm hoặc xếp hạng mà phần mềm có thể lưu trữ và phân tích. API SERP trả về các bản ghi kết quả thô; một API theo dõi xếp hạng chuyên dụng cũng có thể cung cấp các dự án, lịch sử, cảnh báo và báo cáo.

Q: Làm thế nào tôi có thể tìm vị trí của miền trong kết quả tự nhiên?

Phân tích mỗi URL kết quả tự nhiên với một bộ phân tích URL, chuẩn hóa tên miền, áp dụng một chính sách đỉnh/nền tảng rõ ràng, và trả về vị trí được cung cấp của kết quả phù hợp đầu tiên. Tránh việc so khớp chuỗi con.

Q: Vị trí nào tôi nên lưu khi miền bị thiếu?

Lưu một vị trí null hoặc để trống cộng với một trạng thái không được xếp hạng rõ ràng cho độ sâu đã lấy mẫu. Không sử dụng số không và không chuyển tiếp quan sát trước đó.

Q: Bao lâu thì một trình theo dõi xếp hạng nên chạy?

Chọn một chu kỳ dựa trên quyết định mà dữ liệu hỗ trợ. Lấy mẫu hàng ngày là phổ biến cho việc giám sát SEO tích cực, trong khi việc báo cáo chiến lược chậm hơn có thể cần ít hơn. Sự nhất quán và các cài đặt tương đương quan trọng hơn tần suất tối đa.

Q: Liệu kịch bản này có chứng minh một thứ hạng Google phổ quát không?

Không. Nó ghi lại một quan sát có cấu trúc cho truy vấn, thị trường, ngôn ngữ, thiết bị, miền, độ sâu và cài đặt thời gian đã định rõ. Kết quả tìm kiếm có thể thay đổi bên ngoài cấu hình lấy mẫu đó.