Python 網頁爬蟲教學：使用 TalorData SERP API 收集結構化搜尋資料

了解手動解析搜尋 HTML 與使用官方 TalorData Python SDK 收集結構化搜尋資料的實際差異。

網頁爬蟲是從頁面或線上服務中收集資訊的技術。Python 因其可讀性、龐大的生態系統以及與資料、AI 和自動化工具的無縫整合，成為這項工作的熱門選擇。

然而，當目標是搜尋引擎結果頁時，下載 HTML 並猜測 CSS 選擇器的方式往往非常脆弱。搜尋引擎會呈現不同的佈局、要求 JavaScript 執行、套用地區設定，並且在不通知的情況下變更標記結構。TalorData 提供的 SERP API 透過一次經身份驗證的請求即可回傳結構化搜尋資料，讓你的 Python 程式碼直接處理資料欄位，而非頁面標記。

本教學你將學到：對比手動 HTML 爬蟲與 SERP API 的差異，安裝 talordata-serp，發送搜尋請求，讀取結構化結果，處理 JSON 和 HTML 回應模式，對大結果集進行分頁，將資料匯出為 JSON 和 CSV，以及在不消耗真實 API 請求的情況下安全測試整合。

使用 Python 收集搜尋資料的工具

搜尋資料收集有兩種主要方式：自行爬取頁面並解析 HTML，或使用在伺服器端完成收集和標準化的搜尋 API。

本教學聚焦於第三種方式。SDK 使用 Python 標準資料結構，因此你可以將其結果直接傳遞給資料庫、DataFrame 函式庫、LLM 工作流或 CSV 寫入器。

手動 HTML 爬蟲 vs SERP API

使用手動爬蟲時，應用通常遵循以下流程：

1. 建構 URL 並發送 HTTP 請求。
2. 處理狀態碼、請求標頭、JavaScript 渲染和速率限制。
3. 使用 CSS 選擇器解析 HTML 並定位結果區塊。
4. 將欄位標準化為應用特定的 Schema。
5. 當搜尋引擎變更標記時，重複以上維護工作。

使用 TalorData 時，你的應用只需向 /serp/v1/request 發送搜尋參數。SDK 自動新增 Bearer 身份驗證、發送表單編碼資料、解析回傳並回傳類似字典的結果物件。你專注於資料的使用方式，而非資料的取得過程。

import os

from talordata_serp import Client

client = Client(api_token=os.getenv("TALORDATA_API_TOKEN"))
results = client.search(engine="google", q="python data pipelines")

分步驟指南：基礎 TalorData 工作流

以下範例使用 Talordata/talordata-serp-python 儲存庫中的公開介面。

先決條件

• Python 3.8 或更新版本。
• TalorData 帳戶和 API 令牌。
• 基本的 Python 和字典操作知識。
• 用於專案依賴的虛擬環境。

步驟 1：安裝 SDK

python -m pip install talordata-serp

該套件依賴 requests，並從 talordata_serp 模組匯出用戶端和例外類別。

步驟 2：設定 API 令牌

將憑證儲存在原始碼檔案之外。在執行指令碼前設定環境變數：

# macOS / Linux
export TALORDATA_API_TOKEN="paste-your-token-here"

# PowerShell
$env:TALORDATA_API_TOKEN = "paste-your-token-here"

Client 也接受明確的 api_token 參數，適用於金鑰管理器在執行時注入值的場景。

步驟 3：發送首次搜尋

import os

from talordata_serp import Client

client = Client(api_token=os.getenv("TALORDATA_API_TOKEN"))
result = client.search(
    engine="google",
    q="python web scraping",
)

print("status:", result.status)
print("metadata:", result.search_metadata)

client.search() 預設使用 json=1。當回傳包含 JSON 物件時，SDK 會將其包裝在 SerpResults 中，行為與一般 Python 字典一致。

步驟 4：新增請求參數

透過關鍵字參數或映射傳遞參數。設為 None 的值會被自動省略。Python 布林值會被標準化為 "1" 和 "0" 用於表單請求。

params = {
    "engine": "google",
    "q": "python RAG tutorial",
    "location": "Austin, Texas",
    "safe": True,
}

result = client.search(params)
print(result.as_dict())

讀取結構化結果

使用字典存取引擎特定的結果區塊，使用輔助屬性讀取通用元資料：

print(result.status)
print(result.search_metadata)

search_info = result.get("search_information", {})
print(search_info.get("query_displayed"))

# 將包裝器轉換為一般字典，供其他函式庫使用。
payload = result.as_dict()

結果區塊是可選的。當某個欄位可能不會在特定引擎或查詢類型中回傳時，優先使用 get() 或設定預設值。

靜態 HTML 與動態搜尋頁面

傳統的 Python 爬蟲教學通常將頁面分為靜態 HTML 和 JavaScript 密集型內容。靜態頁面有時可以用 requests 取得，而動態頁面可能需要瀏覽器會話和明確的等待邏輯。

SERP API 改變了這一權衡。你的應用始終維持在結構化 API 邊界，無需檢查搜尋頁面的 DOM 來提取標題、連結、摘要或元資料。

# 應用直接消費結構化資料，而非 CSS 選擇器。
organic_results = result.get("organic_results", [])
for item in organic_results:
    print(item.get("title"), item.get("link"))

這並不表示所有網站都能自動被爬取，也不表示 API 可以取代所有瀏覽器自動化。而是說，當你的目標是搜尋結果資料而非與私有 Web 應用的任意互動時，TalorData 是正確的抽象層。

選擇回應模式

SDK 為 TalorData 端點支援的每種輸出格式提供了輔助方法。

結構化 JSON

result = client.search(engine="google", q="pizza")
plain = client.search_json(engine="google", q="pizza")

print(result.status)
print(plain["search_metadata"])

JSON + HTML 組合

模式 json=2 回傳 HTML 和一個巢狀的 JSON 字串。SDK 會在巢狀 JSON 有效時自動嘗試解碼。

combined = client.search(engine="google", q="pizza", json=2)
print(combined.get("html"))
print(combined.get("json", {}).get("search_metadata"))

HTML 或原始回應文字

html = client.search_html(
    engine="google",
    q="pizza",
)
print(html[:500])

raw_body = client.raw_search(engine="google", q="pizza")
print(raw_body[:500])

當你明確需要標記內容時使用 HTML 模式。對於應用邏輯，請盡可能使用預設的 JSON 模式——速度更快，且避免了脆弱的 DOM 解析。

分頁與批次搜尋

分頁由所選引擎支援的參數控制。對於 Google 風格的查詢，通常使用 start 偏移量：

for start in (0, 10, 20):
    page = client.search(
        engine="google",
        q="python web scraping",
        start=start,
    )
    print(start, page.status)

對於小批次任務，一般迴圈清晰且易於監控：

queries = ["Python RAG", "Python SEO", "Python search API"]

for query in queries:
    page = client.search(engine="google", q=query)
    print(query, page.search_metadata.get("status"))

對於更大規模的工作負載，請新增有限並行、日誌記錄和符合帳戶額度的應用級速率限制。SDK 不會靜默重試請求或提供內建分頁器——這使得整合行為顯式且可預測。

匯出搜尋資料

由於 as_dict() 回傳一般 Python 資料，標準庫匯出器無需任何 TalorData 專用適配器即可運作。

匯出為 JSON

import json

with open("search-result.json", "w", encoding="utf-8") as file:
    json.dump(result.as_dict(), file, ensure_ascii=False, indent=2)

匯出指定欄位為 CSV

import csv

organic = result.get("organic_results", [])
with open("organic-results.csv", "w", newline="", encoding="utf-8") as file:
    writer = csv.DictWriter(file, fieldnames=["title", "link", "snippet"])
    writer.writeheader()
    for item in organic:
        writer.writerow({
            "title": item.get("title", ""),
            "link": item.get("link", ""),
            "snippet": item.get("snippet", ""),
        })

生產環境錯誤處理

該套件匯出了針對缺少憑證和常見傳輸故障的命名例外。在應用邊界捕獲它們，以便你的 Worker、CLI 工具或 Web 服務可以報告有用的錯誤狀態。

from talordata_serp import (
    APITokenNotProvided,
    HTTPConnectionError,
    HTTPError,
    TimeoutError,
)

try:
    result = client.search(engine="google", q="pizza")
except APITokenNotProvided:
    print("執行任務前請設定 TALORDATA_API_TOKEN。")
except TimeoutError:
    print("請求逾時。")
except HTTPConnectionError:
    print("無法連線 TalorData。")
except HTTPError as error:
    print("HTTP 狀態碼:", error.status_code)
    print("API 錯誤:", error.error)

設定用戶端級別的逾時或為單個請求覆蓋逾時：

client = Client(
    api_token=os.getenv("TALORDATA_API_TOKEN"),
    timeout=15,
)
result = client.search(engine="google", q="pizza", timeout=10)

無需真實請求即可測試整合

SDK 接受自訂 requests.Session。這允許你使用偽造的 Session 來斷言請求方法、URL、請求標頭和表單載荷——無需暴露憑證，也不消耗真實的 API 請求。

from talordata_serp import Client

class FakeSession:
    def request(self, **kwargs):
        assert kwargs["method"] == "POST"
        assert kwargs["url"].endswith("/serp/v1/request")
        assert kwargs["data"]["json"] == "1"
        raise AssertionError("在真實測試中回傳一個 fixture 回應")

client = Client(api_token="test-token", session=FakeSession())

儲存庫中還包含可執行的範例：examples/ 目錄下的 basic_search.py 和 html_output.py。

重複使用用戶端處理任務

使用一個用戶端處理相關請求，並透過上下文管理器確定性地關閉其 Session：

import os
from talordata_serp import Client

with Client(api_token=os.getenv("TALORDATA_API_TOKEN")) as client:
    first = client.search(engine="google", q="Python")
    second = client.search(engine="google", q="TalorData")

print(first.status, second.status)

為什麼選擇 Python + TalorData？

1. 可讀的整合程式碼：搜尋請求就是一個普通的 Python 函式呼叫。
2. 強大的資料生態：JSON 結果可直接傳遞給 CSV 寫入器、資料庫、DataFrame 和 AI 管道。
3. 可重複使用的工作流：一個用戶端即可驅動搜尋 Copilot、RAG 檢索、SEO 監控、研究任務和定時自動化。
4. 清晰的故障處理：令牌、逾時、連線和 HTTP 錯誤均以命名例外暴露。
5. 更少的頁面維護：你的應用消費回應欄位，而非將業務邏輯耦合到搜尋頁面的 CSS 選擇器。

TalorData 不是通用的瀏覽器自動化框架。它是一個專注的搜尋資料 API。這一邊界使其成為你需要結構化 SERP 資料時的正確選擇。

常見問題

使用 SERP API 和直接爬取網站是一回事嗎？

它們是不同的整合層。手動爬取在你的應用中下載並解析頁面。SERP API 透過經身份驗證的 API 回應暴露搜尋資料。你的應用仍應遵循 API 條款、帳戶額度和適用法律。

本教學需要 Beautiful Soup 或 Selenium 嗎？

不需要。那些工具適用於其他類型的 Web 自動化，但本教學使用 TalorData SDK 直接取得搜尋結果，不會在你的處理程序中解析搜尋頁面的 DOM。

API 令牌應該儲存在哪裡？

本機使用 TALORDATA_API_TOKEN 環境變數，生產環境使用部署金鑰管理器。切勿將真實令牌提交到程式碼儲存庫或放置在瀏覽器端 JavaScript 中。

應該選擇哪種輸出模式？

結構化應用資料使用預設的 JSON 模式。需要明確一般字典時使用 search_json()，需要 HTML 輸出時使用 search_html()，需要未處理的回應體時使用 raw_search()。

完整範例在哪裡？

參見 TalorData Python SDK GitHub 儲存庫取得 README、套件原始碼、測試和可執行範例。使用 官方 SERP API 文件查看引擎特定參數。

以上就是完整的工作流：安裝 SDK、保護令牌、發送結構化搜尋請求、僅匯出應用需要的欄位，並將 API 邊界與業務邏輯分離。接下來，你可以探索 引擎特定參數或瀏覽 SDK GitHub 原始碼。