API Tìm kiếm Google: Từ Truy vấn Tìm kiếm đến JSON Cấu trúc

TL;DR:

• API Tìm kiếm Google không rác trả về kết quả tìm kiếm dưới dạng JSON có cấu trúc. Sử dụng các trường kết quả hữu cơ trong các công cụ nghiên cứu, báo cáo SEO và quy trình phát hiện nguồn.
• Ngữ cảnh tìm kiếm thuộc về kết quả. Giữ lại truy vấn, quốc gia, ngôn ngữ và thời gian quan sát cùng nhau để các so sánh sau này có ý nghĩa rõ ràng.
• Một tác vụ đang chờ xử lý khác với một tập kết quả rỗng. Xử lý HTTP 201 riêng biệt trước khi cố gắng đọc organic_results hoặc tạo một tệp CSV.

Dữ liệu tìm kiếm Google trở nên hữu ích khi một nhóm có thể kết nối mỗi kết quả với câu hỏi và thị trường đã tạo ra nó. Một tiêu đề và URL được sao chép vào bảng tính sẽ mất nhiều ngữ cảnh đó. Một phản hồi có cấu trúc cho phép một ứng dụng bảo tồn nó từ ban đầu.

API Tìm kiếm Google không rác được cập nhật cung cấp một lộ trình quản lý từ truy vấn tìm kiếm đến JSON. Ứng dụng của bạn gửi yêu cầu và quyết định cách sử dụng dữ liệu trả về. Xử lý Proxy và CAPTCHA diễn ra ở phía dịch vụ, giảm thiểu hạ tầng thu thập mà nhóm của bạn cần duy trì.

Hướng dẫn này theo dõi quá trình chuyển giao đó: chọn ngữ cảnh tìm kiếm, gửi yêu cầu, đọc phản hồi và lưu lại một tập dữ liệu mà người khác có thể hiểu.

Những gì API Tìm kiếm Google Trả Về

API Tìm kiếm Google trả về dữ liệu tìm kiếm có cấu trúc, với các kết quả hữu cơ có sẵn trong mảng organic_results cấp cao nhất khi có. Một kết quả tự nhiên có thể bao gồm position, title, link, và snippet. Phản hồi cũng có thể chứa thông tin phân trang và các mô-đun tìm kiếm khác, tùy thuộc vào truy vấn và các kết quả trả về.

Giữ nguyên phản hồi ban đầu trước khi trích xuất một tập con. Một bảng phẳng là thuận tiện cho phân tích, nhưng nó không thể đại diện cho mọi đối tượng lồng nhau mà không có một ánh xạ có chủ đích. mô hình dữ liệu JSON phân biệt các mảng, đối tượng, chuỗi, số, boolean và null; bảo tồn những phân biệt đó giúp cho việc xử lý sau này trở nên dễ dàng hơn.

Một đoạn trích là một đoạn trích kết quả tìm kiếm. Nó không cung cấp nội dung đầy đủ của trang đích. Nếu một ứng dụng nghiên cứu cần chứng cứ của một bài viết, ứng dụng đó phải lấy và xem xét trang đó một cách riêng biệt.

Chuẩn Bị Yêu Cầu Đầu Tiên Nhỏ

Một yêu cầu đầu tiên cần một khóa API Scrapeless, một truy vấn, và một khách hàng có thể gửi JSON qua HTTP. Sử dụng một tài khoản có quyền truy cập vào API Tìm kiếm Google và giữ khóa trong biến môi trường SCRAPELESS_API_KEY.

Đối với ví dụ Python bên dưới, cài đặt gói requests trong môi trường dự án của bạn. Các mô-đun còn lại đến từ thư viện chuẩn của Python. Lưu kịch bản với tên google_search_export.py, sau đó chạy nó với python3 google_search_export.py sau khi thiết lập biến môi trường thông qua shell địa phương của bạn hoặc quản lý bí mật.

Ví dụ sử dụng truy vấn trung lập coffee, quốc gia us, và ngôn ngữ en. Bắt đầu với đầu vào nhỏ này trước khi giới thiệu danh sách từ khóa hoặc một công việc theo lịch. Kiểm tra hình dạng phản hồi trước; mô hình dữ liệu hạ lưu phụ thuộc vào nó.

Yêu cầu đã xác thực là một điều kiện tiên quyết yêu cầu khóa tài khoản của bạn. Hình dạng yêu cầu của ví dụ theo tham chiếu API hiện tại; nó không được trình bày như một phiên chạy tài khoản trực tiếp đã được ghi lại.

Chọn Quốc Gia, Ngôn Ngữ, và Chế Độ Đầu Vào

Quốc gia, ngôn ngữ, và vị trí mô tả các phần khác nhau của một yêu cầu tìm kiếm. gl chọn quốc gia tìm kiếm, hl chọn ngôn ngữ tìm kiếm, và location xác định nơi tìm kiếm nên xuất phát. google_domain chọn miền Google. Tùy chọn thiết bị hiện tại hỗ trợ máy tính để bàn.

Mô hình tham số API Tìm kiếm Google cũng có hai quy tắc đầu vào ảnh hưởng đến cách bạn xây dựng yêu cầu:

• Sử dụng q cho một truy vấn được biểu thị qua các tham số riêng lẻ. Ngoài ra, cung cấp một url Tìm kiếm Google hoàn chỉnh; khi url được cung cấp, các tham số đầu vào khác sẽ bị bỏ qua.
• Chọn location hoặc uule. Chúng không thể được sử dụng cùng nhau.

Để so sánh qua các thị trường, lưu lại đối tượng đầu vào hoàn chỉnh với mỗi phản hồi. Thiết lập cùng một quốc gia và ngôn ngữ khiến ngữ cảnh mong muốn rõ ràng, nhưng nó không đảm bảo kết quả giống nhau qua các quan sát hoặc tái tạo lịch sử tìm kiếm đã đăng nhập của một người cụ thể.
Các truy vấn có thể bao gồm các toán tử như site:, inurl: và intitle:. Sử dụng chúng để thu hẹp câu hỏi nghiên cứu. Một tìm kiếm bị hạn chế theo trang web không phải là một danh sách hoàn chỉnh các trang đã được lập chỉ mục, vì vậy kết quả của nó không nên trở thành một số đếm độ phủ index chính xác.

Yêu cầu JSON và xuất kết quả hữu cơ

Yêu cầu sử dụng POST https://api.scrapeless.com/api/v1/scraper/request, diễn viên scraper.google.search và một tiêu đề x-api-token. Kịch bản lưu phản hồi với thời gian đầu vào và thời gian nhận, sau đó xuất các kết quả hữu cơ sang CSV sau HTTP 200.

Lưu ý: Yêu cầu mạng yêu cầu khóa API Scrapeless của bạn và chưa được thực hiện với tài khoản trực tiếp cho bài viết này. Kịch bản giữ lại phản hồi tác vụ HTTP 201 để kiểm tra; nó không thực hiện việc lấy kết quả tác vụ.

import csv
import json
import os
from datetime import datetime, timezone
from pathlib import Path

import requests


def spreadsheet_text(value):
    text = "" if value is None else str(value)
    if text.lstrip().startswith(("=", "+", "-", "@")) or text.startswith(("\t", "\r")):
        return "'" + text
    return text


def export_results(payload, context, received_at, output_path):
    results = payload.get("organic_results")
    if not isinstance(results, list):
        print("No usable organic_results array; inspect the saved JSON.")
        return
    fields = ["q", "gl", "hl", "received_at", "position", "title", "link", "snippet"]
    with output_path.open("w", encoding="utf-8", newline="") as stream:
        writer = csv.DictWriter(stream, fieldnames=fields)
        writer.writeheader()
        for item in results:
            if not isinstance(item, dict):
                raise ValueError("Unexpected organic result item; inspect the saved JSON.")
            row = {name: item.get(name) for name in ("position", "title", "link", "snippet")}
            row.update(context, received_at=received_at)
            writer.writerow({name: spreadsheet_text(row.get(name)) for name in fields})
    print(f"Exported {len(results)} organic results to {output_path}")


def main():
    context = {"q": "coffee", "gl": "us", "hl": "en"}
    response = requests.post(
        "https://api.scrapeless.com/api/v1/scraper/request",
        headers={"x-api-token": os.environ["SCRAPELESS_API_KEY"]},
        json={"actor": "scraper.google.search", "input": context},
        timeout=120,
    )
    response.raise_for_status()
    received_at = datetime.now(timezone.utc).isoformat()
    run_id = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S%fZ")
    payload = response.json()
    record = {"input": context, "received_at": received_at,
              "http_status": response.status_code, "response": payload}
    output = Path(f"google-search-{run_id}.json")
    output.write_text(json.dumps(record, ensure_ascii=False, indent=2), encoding="utf-8")
    if response.status_code == 201:
        print(f"Task pending. Inspect taskId in {output}; no CSV was created.")
        return
    if response.status_code != 200 or not isinstance(payload, dict):
        raise ValueError(f"Unexpected response; inspect {output}")
    export_results(payload, context, received_at, output.with_suffix(".csv"))


if __name__ == "__main__":
    main()

Thời gian chờ 120 là một cài đặt của khách hàng trong ví dụ này, không phải là một lời hứa về thời gian phản hồi của dịch vụ. Thời gian nhận được ghi lại bởi khách hàng sau khi phản hồi đến; đó không phải là dấu thời gian do Google cung cấp.

Trình viết CSV của Python xử lý các dấu phân cách và các trường được trích dẫn. Trợ lý cũng thêm các ký hiệu công thức bảng tính chung vào văn bản được xuất. Giữ nguyên JSON như bản ghi gốc, vì CSV là một cái nhìn đã được biến đổi dành cho kiểm tra. Xem lại các cài đặt nhập văn bản trước khi mở các giá trị được lấy từ bên ngoài trong bảng tính.

Ví dụ xuất chỉ q, gl và hl từ đầu vào của nó. Nếu bạn thêm vị trí, miền hoặc độ lệch phân trang, hãy kéo dài các cột CSV để giữ các kích thước đó. JSON đã lưu chứa đối tượng đầu vào đầy đủ.

Giải thích phản hồi trước khi xây dựng báo cáo

Phản hồi HTTP 200 chứa dữ liệu tác vụ, trong khi HTTP 201 chỉ ra rằng đang xử lý và cung cấp một taskId. Một tác vụ đang chờ không nên tạo ra một quan sát kết quả trống. Kịch bản giữ lại bản ghi JSON của nó và bỏ qua việc xuất CSV trong trường hợp đó.

Đối với các phản hồi dữ liệu thành công, phân biệt một mảng trống với một trường organic_results vắng mặt hoặc không sử dụng. Các mô-đun khác vẫn có thể có mặt. Kịch bản giữ lại phản hồi và yêu cầu bạn kiểm tra khi không tồn tại mảng có thể sử dụng.

Đọc position như vị trí được cung cấp cho kết quả đã trả về đó. Trước khi kết hợp các trang thành một xếp hạng toàn cầu, hãy xác minh cách các điểm cuối số hóa vị trí cho các yêu cầu của bạn. start điều khiển độ lệch kết quả, và thông tin phân trang có thể hướng dẫn các yêu cầu tiếp theo; không có điều nào xác lập rằng mọi kết quả Google có thể được truy xuất.

Đưa dữ liệu tìm kiếm có cấu trúc vào hoạt động

Kết quả tìm kiếm có cấu trúc cung cấp đầu vào cho các quy trình làm việc mà ứng dụng của bạn xây dựng xung quanh API. Đơn vị hữu ích là một kết quả cộng với ngữ cảnh yêu cầu và thời gian quan sát của nó.

• Những bức tranh SEO: lưu lại các quan sát cho một danh sách từ khóa cố định, sau đó so sánh các ngữ cảnh khớp theo thời gian. Lập lịch, lưu trữ và phát hiện thay đổi thuộc về quy trình của bạn.
• Nghiên cứu thương hiệu và đối thủ: xem xét các miền và tiêu đề trang nào xuất hiện cho các truy vấn đã chọn của bạn. Mẫu mô tả những tìm kiếm đó, thay vì tất cả các đề cập trên web hoặc lưu lượng của một trang web.
• Khám phá nguồn AI: truyền các tiêu đề, liên kết và đoạn trích ứng viên vào một bước chọn nguồn. Lấy các trang đầy đủ riêng biệt khi cần bằng chứng, và kiểm tra rằng các tuyên bố được tạo ra khớp với nguồn của chúng.

Đối với một nhóm nội dung, đầu ra đầu tiên có thể là một danh sách đọc ngắn với truy vấn và thị trường được gắn kèm. Đối với một nhà phát triển, nó có thể là một xuất rat lặp lại được sử dụng bởi một báo cáo hiện có. Cả hai đều bắt đầu bằng một bản ghi dữ liệu làm cho phạm vi của nó trở nên rõ ràng.

Sử dụng những ví dụ này cho thông tin công khai mà bạn được phép thu thập và sử dụng. Giữ các trường cần thiết cho tác vụ, bảo vệ thông tin đăng nhập, và xem xét các điều kiện áp dụng cho việc tái sử dụng dòng dưới.

Kết luận

API Tìm kiếm Google cung cấp cho một ứng dụng dữ liệu tìm kiếm có cấu trúc để làm việc. Một tích hợp hữu ích cũng lưu lại đầu vào, kiểm tra trạng thái tác vụ, và tách biệt việc khám phá nguồn từ phân tích sau này. Bắt đầu với một truy vấn duy nhất và kiểm tra JSON đã lưu trước khi mở rộng quy trình làm việc.

Quy trình làm việc yêu cầu Google Search API đã được cập nhật cung cấp các chi tiết kết nối để điều chỉnh ví dụ này cho dự án của riêng bạn.

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

H: Đây có phải là một API do Google cung cấp không?

Bài viết này mô tả API Tìm kiếm Google của Scrapeless, một dịch vụ Scrapeless để truy xuất dữ liệu Tìm kiếm Google. Nó không khẳng định một quan hệ đối tác chính thức với Google.

H: Có cần quản lý trình duyệt hoặc proxy không?

API được quản lý xử lý cơ sở hạ tầng thu thập ở phía dịch vụ. Khách hàng của bạn gửi yêu cầu HTTP và xử lý dữ liệu được trả về.

H: API có bao gồm dữ liệu xếp hạng lịch sử không?
Luồng công việc mô tả ở đây tạo ra lịch sử bằng cách lưu giữ những quan sát của riêng bạn. Nó không lấy lại lịch sử xếp hạng có sẵn trước đó.

Q: Liệu cùng một API có thể tìm kiếm hình ảnh không?

Sản phẩm hỗ trợ tìm kiếm Hình ảnh Google, với tbm=isch được xác định trong tham số tham chiếu. Kiểm tra phản hồi hình ảnh một cách riêng biệt; bảng CSV của bài viết này là dành cho kết quả web tự nhiên.

Q: Một đoạn trích tìm kiếm có chứa toàn bộ trang không?

Một đoạn trích là một đoạn trích gắn liền với một kết quả tìm kiếm. Một luồng công việc cần bằng chứng đầy đủ của trang phải thu thập và xem xét nội dung đích một cách riêng biệt.

Q: Điều gì nên xảy ra khi yêu cầu trả về HTTP 201?

Bảo tồn taskId và coi nhiệm vụ là đang chờ xử lý. Hoàn thành luồng công việc kết quả nhiệm vụ đã được tài liệu trước khi xử lý nó như dữ liệu tìm kiếm đã hoàn thành.