文档

谷歌地图搜索 API

搜索与查询词相关的地点。

请求

POST https://api.serqo.io/v1/search

字段	取值
engine	`google`
type	`maps`

请求头

创建 API Key 并保存在服务端。下面两种鉴权请求头任选一种。

请求头	取值	说明
Content-Type	`application/json`	请求正文为 JSON。
Authorization	`Bearer YOUR_API_KEY`	推荐的鉴权方式。
x-api-key	`YOUR_API_KEY`	替代 Authorization，选择一种鉴权请求头即可。

bash

export SERP_API_KEY='YOUR_API_KEY'

curl https://api.serqo.io/v1/search \
  -H "Authorization: Bearer $SERP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "q": "coffee shops in Seattle",
  "engine": "google",
  "type": "maps",
  "gl": "us",
  "hl": "en"
}'

GET 请求

同一接口也接受 URL 查询参数，API Key 仍放在请求头中。

bash

curl --get https://api.serqo.io/v1/search \
  -H "Authorization: Bearer $SERP_API_KEY" \
  --data-urlencode 'q=coffee shops in Seattle' \
  --data-urlencode 'engine=google' \
  --data-urlencode 'type=maps' \
  --data-urlencode 'gl=us' \
  --data-urlencode 'hl=en'

参数

每次请求返回的结果数量由搜索引擎决定，可能有所变化。继续翻页时请使用响应中的分页信息。

字段	类型	必填	默认值	说明
q	string	是	—	非空查询词。
engine	string	否	google	此 API 使用 google。
type	string	否	web	此 API 使用 maps。
gl	string	否	—	两位小写国家代码，例如 us。
hl	string	否	—	界面语言代码，例如 en。
start	integer	否	—	Google 地图搜索不应用此参数。
safe	off \| active	否	—	Google 地图搜索不应用此参数。
tbs	string	否	—	Google 地图搜索不应用此参数。

API 只要求 q 必填；要执行本页搜索，请保留示例中的 engine 和 type。未知参数返回 422 INVALID_PARAM。

响应

HTTP 状态为 200。以下是统一响应结构的简化示例，不是真实搜索结果。字段和结果分组取决于返回的页面，部分值可能为 null。

JSON

{
  "success": true,
  "requestId": "req_example",
  "data": {
    "engine": "google",
    "results": [],
    "features": {
      "localResults": [
        {
          "position": 1,
          "title": "Example coffee shop",
          "rating": 4.5,
          "reviews": 120,
          "price": "$$",
          "category": "Coffee shop",
          "address": "Example street, Seattle",
          "reviewSnippet": null,
          "placeId": "/g/example"
        }
      ]
    },
    "pagination": {
      "page": 1,
      "start": 0,
      "hasNext": false,
      "nextStart": null
    },
    "meta": {
      "elapsedMs": 250
    },
    "type": "maps",
    "query": {
      "q": "espresso machine",
      "gl": "us",
      "hl": "en",
      "device": "desktop",
      "start": 0
    },
    "searchInformation": {
      "totalResults": null,
      "timeTakenMs": null,
      "displayed": null
    }
  },
  "meta": {
    "cache": "miss"
  }
}

响应字段

字段	类型	说明
data.query	object	传给搜索引擎的查询条件。
data.searchInformation	object	搜索引擎提供的结果数量和耗时信息。
success	boolean	请求是否成功，示例中为 true。
requestId	string	排查问题时使用的请求 ID。
data.type	string	Search type used for this response.
data.engine	string	实际返回结果的搜索引擎。
data.results	array	主要结果列表；如有其他结果分组，也需要读取。
data.features	object	其他结果分组；引擎未返回的分组可能不出现。
data.pagination	object	当前偏移量与下一页信息。
data.meta.elapsedMs	number	本次搜索耗时，单位为毫秒。
meta.cache	string \| null	hit 表示命中，miss 表示未命中，未知时为 null。

结果字段

如有 data.features.localResults，请读取此分组。部分结果也可能出现在 data.results 中，判断结果为空前应检查两者。

字段	类型	说明
data.features.localResults[].position	integer	地点序号。
data.features.localResults[].title	string	地点名称。
data.features.localResults[].rating	number \| null	显示的评分。
data.features.localResults[].reviews	number \| null	显示的评价数量。
data.features.localResults[].price	string \| null	显示的价位范围。
data.features.localResults[].category	string \| null	商家类别。
data.features.localResults[].address	string \| null	显示的地址，可能不完整。
data.features.localResults[].reviewSnippet	string \| null	显示的评价摘录。
data.features.localResults[].placeId	string \| null	从结果中提取的地点标识。

地点还可能包含 phone、website、hours、googlePlaceId、cid 或 imageId。这些字段是可选的，地址也可能不完整。

主要结果条目

字段	类型	说明
data.results[].domain	string \| null	可取得时的目标域名。
data.results[].favicon	string \| null	提供时显示的网站图标。
data.results[].sitelinks	array	结果附带的站点链接列表。
data.results[].sitelinks[].title	string	站点链接标题。
data.results[].sitelinks[].url	string \| null	站点链接目标地址。
data.results[].extensions	object	结果附带的其他属性。
data.results[].snippetHighlightedWords	string[], optional	提供时显示的摘要高亮词列表。
data.results[].position	integer	在当前结果页中的排名，从 1 开始。
data.results[].type	string	结果类别：organic、news、image、video、shopping、local、forum、book、patent 或 ad，可能与请求的 type 参数不同。
data.results[].title	string \| null	结果中显示的标题。
data.results[].url	string \| null	可解析的目标链接，无法取得时可能为 null。
data.results[].displayedUrl	string \| null	搜索引擎显示的 URL 或域名，不一定能直接访问。
data.results[].source	string \| null	来源名称或显示的域名。
data.results[].date	string \| null	提取到的日期文本，不一定是 ISO 时间格式。
data.results[].snippet	string \| null	结果摘要。
data.results[].thumbnail	string \| null	提供缩略图时，值可能是 URL 或内嵌 data URL。
data.results[].duration	string \| null	结果提供的视频时长文本。
data.results[].price	string \| null	结果提供的价格文本。
data.results[].rating	number \| null	结果提供的评分。

分页

此搜索类型不应用 start，不能用它请求另一页结果。

字段	类型	说明
data.pagination.nextUrl	string \| null	搜索引擎提供的下一页 URL；调用本 API 时使用 nextStart。
data.pagination.requestedPage	integer	请求的目标页码；引擎未提供该页时，可能与实际返回页码不同。
data.pagination.page	integer	当前页码。
data.pagination.start	integer	当前结果偏移量。
data.pagination.hasNext	boolean	是否有下一页。
data.pagination.nextStart	integer \| null	下一次请求的偏移量，不可用时为 null。

错误

JSON

{
  "success": false,
  "requestId": "req_example",
  "error": {
    "code": "INVALID_PARAM",
    "message": "Unknown parameter \"page\"",
    "retryable": false
  }
}

字段	类型	说明
error.code	string	用于程序判断的错误码。
error.message	string	请求失败的原因。
error.retryable	boolean	是否建议重试。
error.retryAfterMs	number, optional	重试前至少等待的毫秒数，为可选字段。

HTTP 状态码	含义	处理方式
400	请求无效或搜索类型不支持。	检查查询词及 engine/type 组合。
401	API Key 缺失、无效或已撤销。	检查鉴权请求头和 API Key。
402	额度不足。	检查账户余额。
403	权限或套餐限制。	检查账户权限和套餐限制。
422	参数无效。	根据 error.message 修正对应参数。
429	请求频率或队列达到限制。	按下方重试规则处理。
5xx	服务器或搜索服务失败。	保留 requestId；仅在允许时重试。

重试规则

仅当 error.retryable 为 true 时重试。
如果返回 error.retryAfterMs，至少等待对应的毫秒数后再请求。

额度计费

成功搜索按适用费率扣除额度。
搜索失败或超时不扣除额度。
默认费率下缓存命中免费。发起搜索前，可用余额仍需覆盖完整请求费用。

查看额度计费规则。