Google 搜尋查詢參數詳解：開發者實用指南

Google Search results 並不是只由 keyword 決定。

同一個 query，在改變 country、language、device、page depth、safe search setting 或 search type 後，可能會返回不同結果。對正在開發 SEO tools、AI Agents、RAG pipelines、rank trackers 或 market research systems 的開發者來說，這些控制項和 keyword 本身一樣重要。

這就是 Google Search query parameters 的價值。它們定義搜尋請求的上下文，讓 SERP data 更可重複、更可比較，也更容易被系統使用。

什麼是 Google Search Query Parameters？

Google Search query parameters 是隨搜尋請求一起提交的值，用來控制搜尋內容、搜尋地點、返回結果數量，以及結果類型。

在 Google Custom Search JSON API reference 中，q 是 query parameter，gl 代表終端使用者地理位置，使用兩位國家代碼；hl 設定介面語言；num 控制返回結果數；start 控制分頁起始位置。Google 文件也描述了 safe、searchType、dateRestrict、exactTerms、excludeTerms 和 siteSearch 等參數。

在 SERP API 工作流程中，不同供應商可能會使用不同命名，例如用 query 代替 q，或用 location 代替原始地理參數。概念是一樣的：parameters 告訴 API 如何組織搜尋結果。

核心參數：q

最重要的參數是搜尋 query。

{
  "q": "best project management software"
}

在很多 SERP API 中，它可能寫成：

{
  "query": "best project management software"
}

好的 query 應該足夠具體，能對應使用者意圖。例如 best CRM software 很寬泛，而 best CRM software for small business 更適合 SaaS comparison、SEO tracking 和 AI source discovery。

對 AI Agent 來說，query 通常來自使用者問題。Agent 可以把 prompt 改寫成一到兩個更精準的搜尋 query，再交給 Search API。

Location Parameters：國家、城市與市場

Location 是搜尋結果變化最大的原因之一。

例如 best payroll software 在 United States、United Kingdom、Singapore 或 Australia 可能返回不同頁面。像 dentist near me 或 coffee shop in Seattle 這類 local queries，對地點更敏感。

Google 文件說明，gl parameter 使用兩位國家代碼，會強化與該國來源相符的結果；Google 也提到，設定 gl 可以改善相關性，尤其對國際使用者更明顯。

在 SERP API 中，location 可能寫成：

{
  "location": "United States"
}

或：

{
  "location": "Austin, Texas, United States"
}

對 SEO rank tracking 來說，每條結果都應保存 location。沒有 location 的排名資料，很難比較。

Language Parameters：hl 與結果語言

Language 會影響介面和搜尋體驗。

Google 的 hl parameter 用於設定介面語言。Google 文件說明，明確設定這個參數可以改善搜尋結果的效能和品質。

例如：

{
  "language": "en"
}

對 multilingual SEO 和 AI workflow 來說，language 不是小設定。同一個 keyword，在英文、西班牙文、日文或繁體中文環境下，可能會浮現不同來源。

Device Parameter：Desktop vs Mobile

Google results 在 desktop 和 mobile 上可能不同。

Mobile results 可能更強調 local pack、視覺模組或不同 SERP features。Desktop results 則可能顯示更完整的橫向版面、較長 snippet 或不同廣告位置。

SERP API 可能這樣表示：

{
  "device": "mobile"
}

或：

{
  "device": "desktop"
}

對 SEO monitoring 來說，只有在真的需要時才同時追蹤 desktop 和 mobile，因為這通常會讓資料量翻倍。

Pagination Parameters：num、start 和 page

Pagination 控制返回多少結果，以及結果從哪裡開始。

在 Google Custom Search JSON API 中，num 控制返回搜尋結果數量，值為 1 到 10；start 控制第一條返回結果的索引。Google 文件說明，在預設每頁 10 條結果時，start=11 會從第二頁開始，且 JSON API 不會返回超過 100 條結果。

在 SERP API 中，你可能會看到：

{
  "num": 10,
  "page": 1
}

或：

{
  "start": 0,
  "num": 10
}

對多數 SEO workflow 來說，top 10 或 top 20 已經足夠。對 AI Agent 來說，top 3–5 個高品質來源可能就夠用。深度分頁會增加成本和噪音。

Safe Search 和 Filtering

Safe search 控制是否過濾顯性內容。

Google Custom Search JSON API 將 safe 定義為 search safety level，並提供 active 啟用 SafeSearch filtering、off 關閉 filtering 等值。

Request 可以像這樣：

{
  "safe": "active"
}

對 business、education 或 consumer-facing applications 來說，這個設定可能很重要。對 SEO monitoring 來說，應保持設定一致，避免排名比較失真。

Search Type Parameters

不是每個搜尋 workflow 都需要標準網頁結果。

Google Custom Search JSON API 使用 searchType=image 表示 image search；如果未指定，結果會限制為網頁。在更廣泛的 SERP API 工作流程中，search type 可能包含 organic search、images、news、shopping、local、maps、videos、jobs、flights、hotels 等。

例如：

{
  "engine": "google",
  "type": "news",
  "query": "AI search market trends"
}

對 SEO 來說，search type 可以區分 organic ranking data、news、local、shopping 或 image visibility。對 AI Agent 來說，它可以幫助把任務路由到正確來源類型。

Date 和 Freshness Parameters

當 query 依賴近期資訊時，freshness 很重要。

Google Custom Search JSON API 文件說明，dateRestrict 可以按日期限制結果，支援 days、weeks、months、years，格式包括 d[number]、w[number]、m[number] 和 y[number]。

例如：

{
  "dateRestrict": "m1"
}

對 AI Agent 和 RAG system 來說，date controls 可以幫助避免在回答近期產品、新聞、法規或市場變化時使用過時來源。

SERP API Request 範例

實用的 Google Search request 可能像這樣：

{
  "engine": "google",
  "query": "best SERP API for AI agents",
  "location": "United States",
  "language": "en",
  "device": "desktop",
  "num": 10,
  "page": 1,
  "output": "json"
}

Response 可能包含：

{
  "search_parameters": {
    "engine": "google",
    "query": "best SERP API for AI agents",
    "location": "United States",
    "language": "en",
    "device": "desktop"
  },
  "organic_results": [
    {
      "position": 1,
      "title": "Best SERP APIs for AI Agents",
      "url": "https://example.com/best-serp-api-ai",
      "domain": "example.com",
      "snippet": "Compare SERP APIs for AI agents, RAG workflows, and search grounding.",
      "result_type": "organic"
    }
  ]
}

你可以用 SerpApi、SearchAPI、Bright Data 或 Talordata 這類工具測試這個流程。真正重要的是 response 是否足夠乾淨，能讓 SEO tool、AI Agent 或 RAG pipeline 直接使用。開始免費測試1000次API響應

常見錯誤

第一個錯誤，是追蹤 keyword 時不帶 location。搜尋結果具有市場差異。

第二個錯誤，是混用 desktop 和 mobile data，卻沒有標記 device context。

第三個錯誤，是收集太多頁結果。如果你的 workflow 只使用 top 10 results，page 3 data 可能不值得。

第四個錯誤，是忽略 language。對 international SEO 來說，hl、language 和 market context 都應保存。

第五個錯誤，是沒有把 request parameters 與 response 一起保存。沒有 query、location、language、device、page 和 timestamp，SERP data 就失去上下文。

結語

Google Search query parameters 不只是技術細節，而是在定義搜尋上下文。

對開發者來說，目標不只是發送 query，而是收集可靠、可比較、結構化的搜尋資料。

對 SEO 來說，這代表按 keyword、market、language 和 device 取得穩定排名資料。

對 AI Agent 來說，這代表有乾淨 URL、snippet、domain 和 freshness context 的 source discovery。

對 RAG 來說，這代表保存 metadata，讓來源之後可以被追溯。

FAQ

1. 什麼是 Google Search query parameters？

Google Search query parameters 是用來控制搜尋請求的參數，例如關鍵字、國家、語言、裝置、返回結果數、分頁、搜尋類型和篩選條件。在 SERP API 工作流程中，這些參數可以幫助開發者取得更穩定、更結構化的搜尋結果。

2. 為什麼 Google Search results 會因地點和語言不同而變化？

Google results 會因市場、搜尋意圖、本地商家、新聞內容和排名訊號不同而變化。gl、hl、location 和 language 等參數可以幫助定義搜尋的國家、城市或語言上下文。

3. SEO 排名追蹤最重要的參數有哪些？

對 SEO rank tracking 來說，最重要的參數包括 query、location、language、device、pagination 和 timestamp。沒有這些欄位，就很難比較不同市場或不同時間的排名變化。

4. Query parameters 如何幫助 AI Agent 和 RAG 工作流程？

Query parameters 可以幫助 AI Agent 和 RAG 系統取得更相關的搜尋結果。透過控制地點、語言、搜尋類型和新鮮度，開發者可以減少噪音來源，並為模型提供更乾淨的 URL、snippet、domain 和 metadata。