Loading Light/Dark Toggle
Quay lại blog

Hướng dẫn API Tìm kiếm Google bằng Python: Gửi yêu cầu và xử lý kết quả

Alex Johnson
Alex Johnson

Senior Web Scraping Engineer

12-Nov-2026

Tóm tắt nhanh:

  • Scrapeless Google Search API trả về dữ liệu tìm kiếm có cấu trúc cho Python. Gửi q, gl và hl trong một yêu cầu JSON đã xác thực.
  • HTTP 200 và HTTP 201 cần được xử lý khác nhau. Đọc trực tiếp kết quả đã hoàn tất; giữ lại ID tác vụ đang chờ và truy xuất tác vụ hiện có đó.
  • Một phản hồi HTTP thành công vẫn cần kiểm tra dữ liệu. Xác thực organic_results trước khi sử dụng các dòng.
  • Lưu giữ phản hồi giúp việc phân tích sau này dễ dàng hơn. Lưu JSON trước khi chọn tiêu đề, trích đoạn hoặc liên kết.

Giới thiệu: Biến kết quả tìm kiếm thành dữ liệu dùng được trong Python

Một yêu cầu tìm kiếm chỉ hữu ích cho ứng dụng khi ứng dụng có thể phân biệt được dữ liệu đã hoàn tất với một tác vụ vẫn đang chạy. Một đoạn script nhanh chỉ in response.text giúp bạn khởi động, nhưng nó để lẫn hai trạng thái này vào nhau.

Hướng dẫn Google Search API với Python này xây dựng một client nhỏ cho Scrapeless Google Search API. Bạn sẽ cấu hình một truy vấn, gửi nó, xử lý một tác vụ đang chờ và lưu một phản hồi để một script khác có thể kiểm tra. Ví dụ sử dụng tìm kiếm web thông thường. Ảnh, Local, Video và Shopping có các phần kết quả khác nhau và cần logic kiểm tra riêng.

Đoạn mã giao tiếp với Scrapeless; nó không phải là Custom Search JSON API hay Search Console API của Google. Ứng dụng của bạn nhận được một ảnh chụp kết quả tìm kiếm chứ không phải báo cáo lưu lượng truy cập của trang web của bạn. Nếu bạn đã quen với mô hình yêu cầu actor của Scrapeless, phần bao bọc yêu cầu sẽ trông quen thuộc.

Yêu cầu tiên quyết

Bạn cần Python, gói requests và một khóa API Scrapeless có quyền truy cập dịch vụ. Hãy dùng môi trường ảo cho dự án và cài Requests với python -m pip install requests. Đặt SCRAPELESS_API_KEY trong biến môi trường của tiến trình trước khi chạy script. Giữ khóa tránh xa khỏi file mã nguồn, notebook bạn chia sẻ và log phản hồi.

Biến môi trường cục bộ là một quy ước được chọn cho script này. Header xác thực HTTP là x-api-token. Chúng có nhiệm vụ khác nhau: Python đọc biến này, rồi gửi giá trị của nó trong header tới endpoint API.

Lưu chương trình hoàn chỉnh dưới đây thành google_search.py và chạy nó với python google_search.py. Chương trình tạo serp.json trong thư mục làm việc. Hãy dùng một thư mục riêng cho mỗi lần thử nghiệm nếu bạn muốn giữ lại các phản hồi trước đó.

Cấu hình q, gl và hl

Tham số q cung cấp truy vấn tìm kiếm, gl chọn quốc gia tìm kiếm và hl chọn ngôn ngữ tìm kiếm. Các điều khiển này thuộc về bên trong input, cùng với tên actor trong đối tượng yêu cầu bao quanh.

Field Example What to Check
actor scraper.google.search Giữ actor ở cấp trên cùng
input.q coffee Giữ nguyên chính xác truy vấn bạn muốn so sánh
input.gl us Ghi lại quốc gia được yêu cầu cùng với kết quả
input.hl en Ghi lại riêng ngôn ngữ được yêu cầu

Bắt đầu với đầu vào nhỏ này. Việc thêm vị trí và bộ lọc tìm kiếm ngay lập tức khiến bạn khó xác định tham số nào đã thay đổi một đầu ra. Hãy luôn có sẵn các tham số Google Search hiện tại khi bạn mở rộng yêu cầu.

Gửi body bằng tham số json= của Requests. Nó tuần tự hóa đối tượng Python thành JSON và đặt kiểu nội dung phù hợp. Đối tượng và mảng JSON là những cấu trúc riêng biệt trong định dạng dữ liệu JSON; một phản hồi phân tích cú pháp thành công không tự động có hình dạng đối tượng mà ứng dụng của bạn mong đợi.

Gửi yêu cầu và truy xuất một tác vụ đang chờ

Client gửi một tác vụ tìm kiếm, rồi chỉ kiểm tra endpoint kết quả nếu tác vụ đó vẫn đang được xử lý. Một phản hồi đã hoàn tất được trả về cho bên gọi dưới dạng một dictionary Python.

Hướng dẫn nhanh Google Search sử dụng POST /api/v1/scraper/request. Với API này, HTTP 201 có nghĩa là quá trình xử lý đang diễn ra và bao gồm taskId. Quy trình xử lý kết quả tác vụ truy xuất ID đó với GET /api/v1/scraper/result/{taskId}.
Đây là cách diễn giải mã trạng thái dành riêng cho ứng dụng. Đặc tả ngữ nghĩa HTTP tổng quát định nghĩa các lớp trạng thái, trong khi hợp đồng dịch vụ cho biết client của bạn phải xử lý một tác vụ đang chờ như thế nào.

Chương trình giới hạn số lần kiểm tra kết quả là mười, với khoảng thời gian hai giây. Đó là các thiết lập client ví dụ, không phải giới hạn dịch vụ hay thời gian hoàn thành được bảo đảm. Timeout mạng được áp dụng riêng cho từng yêu cầu. Nếu tác vụ vẫn đang chờ, ngoại lệ sẽ bao gồm ID của nó để một người vận hành có thể giữ lại.

python Copy
import json
import os
import time
from pathlib import Path
from urllib.parse import quote

import requests

BASE = "https://api.scrapeless.com/api/v1/scraper"


def google_search(query):
    headers = {"x-api-token": os.environ["SCRAPELESS_API_KEY"]}
    response = requests.post(
        BASE + "/request", headers=headers,
        json={"actor": "scraper.google.search", "input": query},
        timeout=(10, 60), allow_redirects=False,
    )
    task_id = None
    for poll in range(11):
        response.raise_for_status()
        if response.status_code not in (200, 201):
            raise RuntimeError(f"Unexpected HTTP status: {response.status_code}")
        data = response.json()
        if not isinstance(data, dict):
            raise ValueError("Expected a JSON object")
        if response.status_code == 200:
            return data
        if task_id is None:
            task_id = data.get("taskId")
        if not isinstance(task_id, str) or not task_id:
            raise ValueError("Pending response has no taskId")
        if poll == 10:
            raise TimeoutError(f"Task still pending; retain taskId={task_id}")
        time.sleep(2)
        response = requests.get(
            BASE + "/result/" + quote(task_id, safe=""),
            headers=headers, timeout=(10, 30), allow_redirects=False,
        )


def organic_rows(data):
    rows = data.get("organic_results")
    if not isinstance(rows, list):
        raise ValueError("organic_results is missing or is not an array")
    if not all(isinstance(row, dict) for row in rows):
        raise ValueError("organic_results contains a non-object item")
    return rows


if __name__ == "__main__":
    query = {"q": "coffee", "gl": "us", "hl": "en"}
    try:
        result = google_search(query)
        Path("serp.json").write_text(
            json.dumps(result, ensure_ascii=False, indent=2), encoding="utf-8"
        )
        rows = organic_rows(result)
        print(f"Saved serp.json; organic rows: {len(rows)}")
        for row in rows:
            print(row.get("position"), row.get("title"), row.get("link"))
    except requests.HTTPError as exc:
        raise SystemExit(f"HTTP request failed: {exc.response.status_code}")
    except requests.RequestException:
        raise SystemExit("Network request did not complete")
    except (ValueError, RuntimeError, TimeoutError, KeyError) as exc:
        raise SystemExit(str(exc))

raise_for_status() đầu tiên bắt các phản hồi lỗi HTTP. Việc kiểm tra trạng thái tường minh cũng loại bỏ các trạng thái không lỗi nhưng bất ngờ. Việc phân tích JSON diễn ra sau các kiểm tra đó, và bộ kiểm tra kết quả chỉ chạy sau khi API thông báo tác vụ đã hoàn tất. Mỗi giai đoạn trả lời một câu hỏi khác nhau.

Bắt đầu Scraping với Scrapeless

Tăng sức mạnh quy trình web scraping và tự động hóa của bạn với Scrapeless!
Đăng ký hôm nay để nhận $5 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í ngay trong Bảng điều khiển Scrapeless.

Đọc organic_results Mà Không Mất Phản Hồi Gốc

Mảng organic_results chứa các bản ghi kết quả tự nhiên trong phản hồi đã hoàn tất. Đọc các trường như position, title, snippet và link từ mỗi bản ghi, đồng thời giữ lại đối tượng gốc để kiểm tra.

Yêu cầu coffee cơ bản được dùng khi chuẩn bị hướng dẫn này trả về HTTP 200 và tám bản ghi tự nhiên với gl=us và hl=en. Số lượng đó mô tả một phản hồi. Một yêu cầu về sau cho cùng truy vấn có thể chứa số dòng khác hoặc một bố cục tính năng tìm kiếm khác.

Chương trình lưu JSON trước khi kiểm tra tính hợp lệ của mảng organic. Điều này quan trọng khi một phản hồi hoàn tất có hình dạng bất ngờ: bạn có thể kiểm tra những gì nhận được thay vì mất nó khi việc kiểm tra hợp lệ làm phát sinh ngoại lệ. Giao diện mã hóa và giải mã JSON của Python hỗ trợ giữ cho văn bản không phải ASCII vẫn dễ đọc thông qua ensure_ascii=False.

Xử lý riêng ba trường hợp. Một mảng rỗng là một tập hợp đã được quan sát nhưng không có mục organic. Một khóa không tồn tại thì không có bảo đảm như vậy. Một giá trị sai kiểu là vấn đề về schema. Script chấp nhận trường hợp đầu tiên và dừng ở hai trường hợp còn lại thay vì âm thầm thay thế chúng bằng một danh sách rỗng.

Các liên kết trả về cũng cần ngữ cảnh. Một URL trông trực tiếp là một ứng viên đích; một trung gian của Google cần xử lý thêm trước khi bạn coi nó là website mục tiêu. Hướng dẫn đầu tiên này in ra giá trị trả về mà không khẳng định rằng đích cuối cùng đã được xác minh.

Xử Lý Lỗi Ở Đúng Tầng

Một ngoại lệ nên xác định được giai đoạn thất bại mà không để lộ header xác thực hoặc biến một yêu cầu thất bại thành kết quả rỗng trông hợp lệ.

Quan sát Ý nghĩa đối với Client này Mục kiểm tra tiếp theo
Thiếu biến môi trường Xác thực chưa được cấu hình cục bộ Kiểm tra môi trường của tiến trình
HTTP 400 API từ chối yêu cầu Kiểm tra tên, kiểu và tổ hợp của đầu vào
HTTP 429 Dịch vụ thông báo giới hạn yêu cầu Kiểm tra tần suất yêu cầu và hạn mức tài khoản
Lỗi HTTP khác Không có kết quả hoàn chỉnh nào được chấp nhận Giữ trạng thái và ngữ cảnh yêu cầu để điều tra
JSON không hợp lệ Không thể phân tích thân phản hồi Kiểm tra phản hồi trong log chẩn đoán được kiểm soát
Thiếu mảng organic Payload không khớp với consumer này Kiểm tra JSON đã lưu và chế độ tìm kiếm đã yêu cầu
Đạt giới hạn tác vụ đang chờ Client này không quan sát được việc hoàn tất Giữ lại ID tác vụ và đánh dấu job là chưa hoàn thành

Ví dụ mẫu cố ý tránh in toàn bộ header yêu cầu hoặc thân lỗi từ server. Trong một dịch vụ lớn hơn, hãy ghi log chẩn đoán có cấu trúc với cấu hình truy vấn, trạng thái và ID tác vụ khi có. Ghi lại một lần chạy thất bại tách biệt với các quan sát đã hoàn tất để các báo cáo phía sau không nhầm lẫn thất bại với vắng mặt dữ liệu.

Kết Luận: Giữ Client Đầu Tiên Nhỏ Gọn

Một client Google Search API Python hữu ích có một đường đi rõ ràng: gửi một truy vấn, truy xuất tác vụ hiện có nếu cần, giữ lại phản hồi, và xác thực các trường mà ứng dụng của bạn sử dụng. Khi đường đi đó đã hoạt động, hãy thêm từng chiều đầu vào một.
Sử dụng thông tin chi tiết về sản phẩm Google Search API để chọn dịch vụ và bảng giá hiện tại để lập kế hoạch thu thập lặp lại. Giữ cấu hình request bên cạnh mọi phản hồi đã lưu trước khi xây dựng bộ dữ liệu lớn hơn.

Xây Dựng Quy Trình Dữ Liệu Tìm Kiếm Của Bạn

Tham gia cộng đồng các lập trình viên làm việc với dữ liệu tìm kiếm: Discord · Telegram.

Tạo một tài khoản Scrapeless và áp dụng hướng dẫn này cho một tập truy vấn nhỏ trước khi lên lịch thu thập quy mô lớn hơn.

Câu Hỏi Thường Gặp

Hỏi: Python có thể gọi Google Search API mà không cần SDK không?

Có. Ví dụ sử dụng Requests và endpoint HTTP được ghi lại. Nó không yêu cầu tác nhân AI hoặc SDK dành riêng cho framework.

Hỏi: HTTP 201 có chứa kết quả tìm kiếm cuối cùng không?

Đối với API này, HTTP 201 cho biết một tác vụ đang chờ xử lý. Giữ lại taskId và truy xuất tác vụ đó thông qua endpoint kết quả.

Hỏi: gl=us có chứng minh rằng mọi kết quả đều là của Mỹ không?

Không. Quốc gia là đầu vào tìm kiếm, không phải nhãn quốc tịch cho mọi trang được trả về. Độ chính xác theo địa phương cần một phương pháp kiểm chứng riêng.

Hỏi: Một khóa organic_results bị thiếu có nên trở thành một danh sách rỗng không?

Không. Một khóa bị thiếu và một mảng trống được khai báo rõ ràng là hai quan sát khác nhau. Kiểm tra cấu trúc phản hồi trước khi báo cáo rằng không có bản ghi organic nào được trả về.

Hỏi: Bạn có cần cấu hình proxy riêng không?

Request cơ bản này không cần cấu hình proxy riêng. API xử lý việc thu thập; hãy tham khảo hợp đồng tham số trước khi thêm cài đặt truyền tải hoặc vị trí.

Hỏi: Script có xác minh nội dung phía sau mọi liên kết kết quả không?

Không. Nó thu thập một ảnh chụp nhanh kết quả tìm kiếm. Việc xác minh đích đến và kiểm chứng nội dung trang là các bước riêng biệt.

Tại Scrapless, chúng tôi chỉ truy cập dữ liệu có sẵn công khai trong khi tuân thủ nghiêm ngặt các luật, quy định và chính sách bảo mật trang web hiện hành. Nội dung trong blog này chỉ nhằm mục đích trình diễn và không liên quan đến bất kỳ hoạt động bất hợp pháp hoặc vi phạm nào. Chúng tôi không đảm bảo và từ chối mọi trách nhiệm đối với việc sử dụng thông tin từ blog này hoặc các liên kết của bên thứ ba. Trước khi tham gia vào bất kỳ hoạt động cạo nào, hãy tham khảo ý kiến ​​cố vấn pháp lý của bạn và xem xét các điều khoản dịch vụ của trang web mục tiêu hoặc có được các quyền cần thiết.

Bài viết phổ biến nhất

Danh mục