> ## Documentation Index
> Fetch the complete documentation index at: https://docs.querying.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Google 地点结果 API（GOOGLE_PLACES）

> 针对本地搜索，以你选择的城市为位置，获取 Google 地点列表中最多 100 个地点。

`GOOGLE_PLACES` 返回 Google 搜索的“地点”标签页针对某个查询列出的地点，也就是本地结果包下方“更多地点”打开的列表。它每页读取 20 个地点，最多读取 5 页，并且每一页都从同一个城市搜索，因此你能按 Google 在该城市的排序获得最多 100 个地点。可用于在整个城市的本地列表中追踪商家排名，或收集 Google 在某个城市为某项服务展示的商家。

| | |
| - | - |
| `taskType` | `GOOGLE_PLACES` |
| 输入 | `query`（必填）；`city` 或 `uule`、`limit`、`country` |
| 积分 | 每读取一个地点页 1 积分。每页包含 20 个地点。 |
| 国家 | 默认 `US`。可使用任意 ISO 3166-1 alpha-2 代码。 |
| 位置 | 用 `city` 或 `uule` 指定。见[地区与位置](https://docs.querying.ai/zh/engines/capacity.md)。 |

## 请求

下面的请求获取在罗得岛州曼维尔搜索长期护理机构时 Google 列出的前 100 个地点：

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskType": "GOOGLE_PLACES", "payload": { "query": "long term care near me", "city": "Manville, Rhode Island, United States", "limit": 100 } }'
```

如果你的系统已为每个地点保存了 Google 的 `uule`，可以用它代替 `city`。下面的值对应内华达州里诺：

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskType": "GOOGLE_PLACES", "payload": { "query": "Reno attorney", "uule": "w+CAIQICIbUmVubywgTmV2YWRhLCBVbml0ZWQgU3RhdGVz", "limit": 100 } }'
```

任务异步执行。按[异步任务](https://docs.querying.ai/zh/concepts/async-tasks.md)中的说明读取结果。`limit: 100` 的任务通常在一到两分钟内完成。

## 参数

| 字段 | 必填 | 说明 |
| - | - | - |
| `query` | 是 | 搜索查询，1-100,000 个字符。缺少 `query` 时接受 `prompt`。 |
| `city` | 否 | 搜索所在的地点，按 Google 对地点的命名书写（城市、州或地区、国家），例如 `"Reno, Nevada, United States"`。最多 100 个字符。结果以 `city` 返回同一值。 |
| `uule` | 否 | Google 自己的位置参数（`w+` 形式），即排名追踪工具保存的值，原样发送给 Google。`city` 和 `uule` 二选一。结果以 `uule` 返回同一值。 |
| `limit` | 否 | 要返回的地点数，1 到 100 的整数。默认 `20`，即一页。要获取完整列表请发送 `100`。 |
| `country` | 否 | 要搜索的 Google 市场，默认 `US`。 |

不发送 `city` 和 `uule` 时，由 Google 决定搜索位置。

## 响应

例如上面曼维尔请求的结果：

```json theme={"theme":"css-variables"}
{
  "places": [
    {
      "position": 1,
      "page": 1,
      "name": "...",
      "placeId": "...",
      "location": { "address": "...", "...": "..." },
      "mapsUrl": "https://maps.google.com/?cid=...",
      "reviews": [{ "...": "..." }],
      "category": "..."
    },
    { "position": 21, "page": 2, "...": "..." }
  ],
  "pages": 5,
  "city": "Manville, Rhode Island, United States"
}
```

| 字段 | 说明 |
| - | - |
| `places` | 始终存在，按 Google 的顺序排列。每个地点带有与 [Google 搜索](https://docs.querying.ai/zh/engines/google-serp.md) `map` 中本地结果包地点相同的字段，Google 展示了哪些就返回哪些：`name`、`placeId`、`location`（`address`、`latitude`、`longitude`）、`phoneNumber`、`url`、`mapsUrl`、`reviews`、`category`、`price`、`snippet`、`image`。 |
| `places[].position` | 地点在整个列表中的排名，从 1 开始，跨页累计。 |
| `places[].page` | 地点所在的地点页，1 到 5。 |
| `pages` | 读取的地点页数。任务按此计费。 |
| `googleLocation` | Google 显示的搜索位置。仅在页面显示位置时返回。 |
| `city` | 你发送的 `city`（如有发送）。 |
| `uule` | 你发送的 `uule`（如有发送）。 |

后面的页面再次列出的地点只计一次。如果 Google 的列表在达到 `limit` 之前结束，`places` 会包含 Google 列出的全部地点；小城镇常常不足 100 个。Google 没有为某个地点展示的字段会被省略。除 `name`、`position` 和 `page` 外，请把每个字段都当作可选字段。

## 积分

每读取一个地点页扣 1 积分。提交时，任务按 `limit` 所需的页数冻结积分，每 20 个地点一页：默认为 1，`limit: 100` 为 5。完成时按实际读取的页数扣费，因此 Google 的列表在第 3 页结束时扣 3 积分。失败的任务扣 0。见[积分与限制](https://docs.querying.ai/zh/concepts/credits-and-limits.md)。

## 限制与错误

* 已完成任务中的 `places` 为空，表示 Google 在该位置没有为该查询列出任何地点。返回前会在第二个浏览器上确认，并扣 1 积分。
* 超出 1-100 的 `limit`、为空或超过 100 个字符的 `city`，或与 `uule` 或 `location` 一起发送的 `city`，返回 `422 VALIDATION_ERROR`。
* 不是 `w+` 形式 UULE 的 `uule` 返回 `400 VALIDATION_ERROR`。
* `location` 返回 `422`。请用 `city` 或 `uule` 指定地点。
* `include.rawResponse` 不起作用，`include.html` 和 `include.analysis` 返回 `422`。见[Markdown 与原始响应](https://docs.querying.ai/zh/engines/response-options.md)。
* 其他请求错误见[错误](https://docs.querying.ai/zh/concepts/errors.md)。

## 相关内容

* [Google 搜索](https://docs.querying.ai/zh/engines/google-serp.md)：带本地结果包的单个结果页
* [地区与位置](https://docs.querying.ai/zh/engines/capacity.md)
* [积分与限制](https://docs.querying.ai/zh/concepts/credits-and-limits.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.