> ## 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.

# Place Lookup：查看每个 AI 引擎用哪条地点信息展示门店

> 就一家门店询问 ChatGPT、Gemini、Google、Copilot 和 Naver，读取每个引擎中该门店的地点信息：来自哪个地图数据库、显示了什么，以及与门店自身信息不同的地方。

用 Place Lookup 查看 AI 引擎如何展示一家门店、分店或诊所。每个引擎都从某个地图数据库展示地点信息。Gemini、Copilot 和 Google 搜索结果页展示 Google 地图的信息，Naver AI Tab 展示 Naver Place 的信息，ChatGPT 展示来自 Yelp、Tripadvisor、Google 地图等数据源的信息。查询结果告诉你每个引擎用了哪条地点信息、哪里有误，让你知道该修改哪个平台上的信息。

## 提交查询

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/place-lookup \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "place": {
      "name": "Canlis",
      "address": "2576 Aurora Ave N, Seattle, WA 98109",
      "location": { "latitude": 47.6430534, "longitude": -122.3467361 },
      "phone": "(206) 283-3313",
      "website": "https://canlis.com/"
    },
    "country": "US",
    "idempotencyKey": "canlis-2026-10"
  }'
```

查询会向每个引擎提出两个问题。每个问题都是该引擎的普通任务，响应列出这些任务：

```json theme={"theme":"css-variables"}
{
  "success": true,
  "lookup": { "id": "canlis-2026-10" },
  "tasks": [
    {
      "engine": "CHATGPT",
      "ask": 1,
      "success": true,
      "task": {
        "id": "9d02deef-...",
        "taskType": "CHATGPT",
        "status": "QUEUED",
        "priority": 1,
        "createdAt": "2026-10-20T09:00:00.000Z",
        "idempotencyKey": "canlis-2026-10:CHATGPT:1"
      }
    },
    { "engine": "CHATGPT", "ask": 2, "success": true, "task": { "...": "..." } },
    { "engine": "GEMINI", "ask": 1, "success": true, "task": { "...": "..." } }
  ]
}
```

用 `GET /v1/place-lookup/{id}` 读取查询，直到 `lookup.status` 为 `COMPLETED`。大多数查询在两分钟内完成，因此每 5 到 10 秒轮询一次。查询不发送 webhook。请求 schema 见 [API 参考](/zh/api-reference/place-lookup.md)。

```bash theme={"theme":"css-variables"}
curl https://api.querying.ai/v1/place-lookup/canlis-2026-10 \
  -H "Authorization: Bearer $QUERYING_API_KEY"
```

## 请求字段

| 字段 | 必填 | 说明 |
| - | - | - |
| `place.name` | 是 | 门店名称，1–200 个字符。连锁店请带上分店名，例如 `Anchorhead Coffee Downtown Seattle`。 |
| `place.address` | `address` 或 `location` | 街道地址，最多 500 个字符。 |
| `place.location` | `address` 或 `location` | 门店的图钉位置 `{ "latitude", "longitude" }`，十进制度数。提供后，每条地点信息都会带上与门店的距离，并报告位置错误的图钉。 |
| `place.phone` | 否 | 官方电话号码，最多 50 个字符，格式不限。每条地点信息的电话都会与它比较。 |
| `place.website` | 否 | 官方网站，`http` 或 `https` URL。每条地点信息的网站都会按站点与它比较。 |
| `place.googlePlaceId` | 否 | 门店的 Google Place ID，例如 `ChIJRXCfNwUVkFQRxraD8U-dANE`。带有此 ID 的地点信息就是该门店。 |
| `place.naverPlaceId` | 否 | 门店的 Naver Place ID，或该地点的 `map.naver.com` 或 `place.naver.com` 页面。带有此 ID 的地点信息就是该门店。 |
| `place.yelpUrl` | 否 | 门店的 `yelp.com/biz/...` 页面。这家商家的地点信息就是该门店。 |
| `country` | 是 | 门店所在国家的 ISO 3166-1 alpha-2 代码，例如 `US` 或 `KR`。 |
| `engines` | 否 | 要询问的引擎，不可重复：`CHATGPT`、`GEMINI`、`GOOGLE`、`BING_COPILOT` 和 `NAVER_AI_TAB`。默认：`KR` 为全部五个，其他国家为前四个。`NAVER_AI_TAB` 仅用于 `KR`。 |
| `idempotencyKey` | 否 | 查询的 id，1–200 个字符，首尾不能有空格。不提供时由服务器生成 UUID。参见[重新发送查询](#重新发送查询)。 |
| `priority` | 否 | 整数 `1`–`10`，默认 `1`，设置在每个任务上。不保证执行顺序。 |

其他字段（包括 `webhook`）返回 `400 VALIDATION_ERROR`。

## 查询如何提问

每个引擎收到两个问题。ChatGPT、Gemini 和 Copilot 被要求在地图上显示门店，第二次附上地址。Google 搜索结果页先搜索门店位置，再从门店的图钉位置搜索门店名称。Naver AI Tab 先被问门店位置，再被问门店名称。

| 引擎 | 第一个问题 | 第二个问题 |
| - | - | - |
| `CHATGPT`、`GEMINI`、`BING_COPILOT` | `Show {name} on a map` | `Show {name}, {address} on a map` |
| `GOOGLE` | `{name} location` | 从 `place.location` 搜索的 `{name}` |

`KR` 门店用韩语提问，但 ChatGPT 的第二个问题是英语的 `Show {name} on a map`，因为用英语提问时 ChatGPT 更常展示韩国门店的地点卡片。没有 `place.address` 时，第二个问题附加地址的引擎会把第一个问题再问一次。没有 `place.location` 时，在 `KR` 以外，Google 的第二次搜索会附上地址。结果中的 `via[]` 原样显示实际发送的每个问题。

## 读取结果

只保留主要字段时，Canlis 的查询结果如下：

```json theme={"theme":"css-variables"}
{
  "success": true,
  "lookup": {
    "id": "canlis-2026-10",
    "status": "COMPLETED",
    "place": {
      "name": "Canlis",
      "address": "2576 Aurora Ave N, Seattle, WA 98109",
      "location": { "latitude": 47.6430534, "longitude": -122.3467361 },
      "phone": "(206) 283-3313",
      "website": "https://canlis.com/"
    },
    "country": "US",
    "engines": [
      {
        "engine": "CHATGPT",
        "status": "COMPLETED",
        "found": true,
        "via": [
          {
            "taskType": "CHATGPT",
            "prompt": "Show Canlis on a map",
            "taskId": "9d02deef-...",
            "status": "COMPLETED",
            "collectedAt": "2026-10-19T16:38:48.957Z",
            "places": 1
          },
          {
            "taskType": "CHATGPT",
            "prompt": "Show Canlis, 2576 Aurora Ave N, Seattle, WA 98109 on a map",
            "taskId": "91505c8f-...",
            "status": "COMPLETED",
            "collectedAt": "2026-10-19T16:39:04.194Z",
            "places": 1
          }
        ],
        "record": {
          "position": 1,
          "name": "Canlis",
          "source": "yelp",
          "provider": "yelp-feed",
          "url": "https://www.yelp.com/biz/canlis-seattle?adjust_creative=openai",
          "address": "2576 Aurora Ave N, Seattle, WA 98109, United States",
          "latitude": 47.6430933,
          "longitude": -122.3467535,
          "phone": "+1 206-283-3313",
          "rating": 4,
          "reviewCount": 1935,
          "website": "https://canlis.com/",
          "match": {
            "same": true,
            "by": ["phone", "website", "location", "address", "name"],
            "nameScore": 1,
            "distanceMeters": 5
          }
        }
      },
      {
        "engine": "GEMINI",
        "status": "COMPLETED",
        "found": true,
        "via": [{ "...": "..." }],
        "record": {
          "position": 1,
          "name": "Canlis",
          "source": "google_maps",
          "placeId": "ChIJRXCfNwUVkFQRxraD8U-dANE",
          "url": "https://maps.google.com/?cid=15060210120606856902",
          "phone": "+1 206-283-3313",
          "rating": 4.6,
          "reviewCount": 2892,
          "website": "https://canlis.com/",
          "match": {
            "same": true,
            "by": ["phone", "website", "location", "address", "name"],
            "nameScore": 1,
            "distanceMeters": 5
          }
        }
      },
      {
        "engine": "GOOGLE",
        "status": "COMPLETED",
        "found": false,
        "via": [
          {
            "taskType": "GOOGLE",
            "query": "Canlis location",
            "taskId": "6d3c3a73-...",
            "status": "COMPLETED",
            "collectedAt": "2026-10-19T16:38:43.932Z",
            "places": 0
          },
          {
            "taskType": "GOOGLE",
            "query": "Canlis",
            "location": { "latitude": 47.6430534, "longitude": -122.3467361 },
            "taskId": "980a858a-...",
            "status": "COMPLETED",
            "collectedAt": "2026-10-19T16:38:48.902Z",
            "places": 0
          }
        ]
      },
      {
        "engine": "BING_COPILOT",
        "status": "COMPLETED",
        "found": true,
        "via": [{ "...": "..." }],
        "record": {
          "name": "Canlis",
          "source": "google_maps",
          "placeId": "ChIJRXCfNwUVkFQRxraD8U-dANE",
          "openState": "Closed · Opens 5 PM Tue",
          "...": "..."
        }
      }
    ],
    "summary": {
      "foundIn": ["CHATGPT", "GEMINI", "BING_COPILOT"],
      "notFoundIn": ["GOOGLE"],
      "failed": [],
      "pending": [],
      "differences": []
    },
    "credits": 10
  }
}
```

ChatGPT 展示了这家餐厅的 Yelp 信息。Gemini 和 Copilot 展示了同一条 Google 地图信息，Place ID 相同。Google 搜索结果页两个问题都没有展示地点，所以它的 `found` 为 `false`。

### `engines[]`

| 字段 | 说明 |
| - | - |
| `engine` | 被询问的引擎。 |
| `status` | 两个问题结束前为 `PROCESSING`，结束后为 `COMPLETED`。两个问题都失败时为 `FAILED`。 |
| `found` | 回答展示了门店时为 `true`。两个问题都结束且没有回答展示门店时为 `false`。还有问题在运行时，以及两个问题都失败时为 `null`。 |
| `via[]` | 实际发送的问题：`prompt` 或 `query`、发送时的 `location`、问题开始后的 `taskId`、`status`、`collectedAt`、`places`（回答展示的地点数），以及失败问题的 `error`。问题等待套餐空位期间，`status` 为 `PENDING`。 |
| `record` | 门店的地点信息：两个回答的地点中与门店匹配最强的一条。`found` 为 `true` 时出现。 |
| `issues` | `record` 中的错误。仅在有错误时出现。 |

### `record`

| 字段 | 说明 |
| - | - |
| `source` | 地点信息所属的地图数据库：`google_maps`、`naver_place`、`yelp`、`tripadvisor`，回答中看不出时为 `unknown`。 |
| `placeId`、`url` | 在来源中的 ID 和页面，例如 Google Place ID 及其 Google 地图链接。 |
| `name`、`address`、`latitude`、`longitude`、`phone`、`website` | 引擎显示的信息。只包含回答中有的字段。 |
| `category`、`rating`、`reviewCount`、`openState`、`image`、`description` | 引擎显示的其他信息，有时才出现。 |
| `position` | 在回答的地点中的顺序，从 1 开始。 |
| `provider` | 仅 ChatGPT：ChatGPT 标明的数据源，例如 `yelp-feed` 或 `bright-feed`。 |
| `localName` | 仅 ChatGPT：地点的另一个名称，例如韩国门店的韩语名称。 |
| `resolvedBy` | 仅 ChatGPT：ChatGPT 根据模型写出的地址找到该地点时为 `address`。这样的地点信息可能属于该地址的另一家商家。 |
| `closed` | 仅 ChatGPT：标为停业时为 `permanently` 或 `temporarily`。 |
| `match` | 判定这条信息就是该门店的依据。`by` 列出一致的信息：`place_id`、`phone`、`website`、`location`、`address` 和 `name`。`nameScore` 是 0 到 1 的名称相似度，`distanceMeters` 是从 `place.location` 到该信息图钉的距离。 |

### `issues`

| 问题 | 含义 |
| - | - |
| `phone_mismatch` | 电话与 `place.phone` 不同；未提供 `place.phone` 时，与多数其他引擎显示的号码不同。 |
| `website_mismatch` | 网站与 `place.website` 不是同一站点；未提供 `place.website` 时，与多数其他引擎显示的站点不同。 |
| `location_mismatch` | 图钉距 `place.location` 超过 300 m。 |
| `other_business_record` | 很可能是门店所在位置另一家商家的信息：电话和网站都不同，或 ChatGPT 按地址找到且其中一项不同。 |
| `closed_permanently`、`closed_temporarily` | ChatGPT 将该地点显示为停业。 |

连锁店所有分店共用的号码（例如免费热线）不参与比较。

### `summary` 与 `credits`

| 字段 | 说明 |
| - | - |
| `summary.foundIn` | 展示了门店的引擎。 |
| `summary.notFoundIn` | 回答已完成但没有门店的引擎。 |
| `summary.failed` | 两个问题都失败的引擎。 |
| `summary.pending` | 仍在回答、尚未展示门店的引擎。 |
| `summary.differences[]` | 各引擎地点信息不一致的地方。`field` 为 `name`、`phone`、`website` 或 `location`，`values[]` 列出每个 `value` 及显示该值的 `engines`。两个图钉相距超过 300 m 时出现 `location` 项，并带有 `spreadMeters`，即相距最远的两个图钉的距离。 |
| `credits` | 到目前为止该查询的问题已扣除的积分。 |

所有引擎结束前 `lookup.status` 为 `PROCESSING`，之后为 `COMPLETED`。每次读取都会根据保存的回答重新判定结果，任务完成后 24 小时内可以读取查询。

## 重新发送查询

每个问题都是键为 `{lookup id}:{engine}:{ask}` 的任务，例如 `canlis-2026-10:GEMINI:2`。用同一 `idempotencyKey` 重新发送同一请求时，查询返回已有的任务，并发送尚无任务的问题，例如因积分不足被拒绝的问题。以同一 id 发送不同的门店、国家或引擎列表会返回 `409 RESOURCE_ALREADY_EXISTS`，不会创建任何任务。以后要再次查询同一门店，请使用新的 `idempotencyKey`。

## 套餐并发

每个问题在套餐并发上限中计为一个任务。查询按套餐剩余的空位开始问题，其余问题在 `tasks[]` 中以 `status: "PENDING"` 等待：

```json theme={"theme":"css-variables"}
{ "engine": "GEMINI", "ask": 1, "success": true, "status": "PENDING" }
```

等待的问题会在正在运行的任务完成后 1 分钟内，或在下次读取查询时自动开始，因此一次请求即可跑完整个查询。Free 套餐允许 2 个并发任务，查询每次运行两个问题，需要几分钟。付费套餐从 50 个并发任务起步，账户有空位时整次查询会一次开始。引擎队列已满或密钥用完每日积分上限时，问题也会等待。问题的价格在问题开始时冻结。在此之前，如果发送查询的密钥被吊销或过期，等待中的问题会以 `API_KEY_INACTIVE` 变为 `FAILED`，花费 0 积分。参见[积分与限制](/zh/concepts/credits-and-limits.md#套餐并发)。

## 错误与计费

询问该国全部默认引擎的一次查询为 10 积分。每个问题按其份额计价：`KR` 的 10 个问题每个 1 积分，其他国家的 8 个问题每个 1.25 积分。只问部分引擎的查询按发送的问题计费。每个问题的价格在提交时冻结，完成时扣除；失败的问题为 0。参见[积分与限制](/zh/concepts/credits-and-limits.md)。

### 提交时被拒绝

| 状态 | 代码 | 原因 |
| - | - | - |
| `400` | `VALIDATION_ERROR` | 请求体不是有效的 JSON、字段缺失或无效、发送了未知字段或 `webhook`，或在 `KR` 以外询问了 `NAVER_AI_TAB`。`details` 指明字段。 |
| `409` | `RESOURCE_ALREADY_EXISTS` | `idempotencyKey` 对应的是另一门店、国家或引擎列表的查询。 |

所有问题都被拒绝时，第一个拒绝以其自身状态作为响应，例如 `402 INSUFFICIENT_CREDITS` 或 `403 KEY_SCOPE_DENIED`，且不会创建任何任务。部分问题被接收时，响应为 `200`，每个被拒绝的问题在 `tasks[]` 中带有 `error`：

```json theme={"theme":"css-variables"}
{
  "engine": "GOOGLE",
  "ask": 2,
  "success": false,
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "insufficient credits (need 1.25)",
    "timestamp": "2026-10-20T09:00:00.000Z"
  }
}
```

### 读取查询

对于账户从未使用过的 id，以及任务已超过 24 小时窗口的查询，`GET /v1/place-lookup/{id}` 返回 `404 RESOURCE_NOT_FOUND`。失败的问题在 `via[]` 中显示 `status: "FAILED"` 和以代码开头的 `error`，例如 `ENGINE_NO_RESULT`。这些代码与该引擎任务的代码相同；在开始前就结束的等待问题带有 `API_KEY_INACTIVE` 或 `INSUFFICIENT_CREDITS`。参见[错误](/zh/concepts/errors.md)。

## 后续步骤

> **[ChatGPT](/zh/engines/chatgpt.md)**
>
> ChatGPT 展示的地点卡片，即 `map`。

> **[批次与网格](/zh/concepts/bulk-submission.md)**
>
> 从门店周围网格的每个点提出同一条提示词。


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