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。