推出 Google Places

在你选择的城市中，获取 Google Places 标签页为搜索词列出的地点，最多 100 个，附带地址、坐标、电话、网站和评分。每 20 个地点 1 积分。

获得的结果

• GOOGLE_PLACES：一个任务读取从你选择的城市搜索时 Google Places 标签页显示的列表，最多 100 个地点。
• places：每个地点包含 name、position 和所在的 page，以及 location（地址、纬度和经度）、phoneNumber、url、mapsUrl、placeId、含评分和评价数的 reviews、category 和 Google 显示的评价摘录。
• pages：任务读取的页数（每页 20 个地点），按此页数计费。

工作原理

发送 query 和 city，city 按 Google 的写法填写，例如 Reno, Nevada, United States。如果你的排名追踪工具已为某个地点保存了 Google 的 uule 值，把它作为 uule 发送，Google 就会从该地点搜索。country 设置市场，默认 US。

Google 每页显示 20 个地点。用 limit 设置需要的数量，1 到 100（默认 20），任务会按 Google 的顺序读取最多五页。position 跨页连续计数，Google 在后面页面重复显示的地点只计一次。Google 的列表在达到 limit 之前结束时，你会收到 Google 显示的全部地点。

任务在每一页都会确认 Google 搜索时所在的位置，因此一个列表中的地点都来自同一个城市。

应用场景

• 追踪在你的城市搜索所属品类时，你的店铺在 Google 列出的所有地点中排第几，范围超出 local pack 的三个地点。
• 在你经营的每个城市发送同一个搜索词，比较各个市场的领先商家。
• 把地点列表与同一搜索词的 Google AI Overview 和 AI Mode 回答放在一起，查看回答推荐了哪些地点。
• 在 Playground 中试用：在搜索标签页选择 Google Places，输入城市，并设置最多 100 个地点。

发送请求

在 Authorization 请求头中带上 API 密钥发送请求。

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",
      "city": "Reno, Nevada, United States",
      "limit": 100,
      "country": "US"
    }
  }'

请求字段

taskTypestring必填

要运行的引擎，例如 CHATGPT 或 GOOGLE。

payload.querystring必填

按用户在搜索框中输入的方式写的搜索词。

payload.citystring

搜索所在的城市，按 Google 的写法填写，例如 Reno, Nevada, United States。最多 100 个字符。一个任务使用 city 或 uule 其中之一。

payload.uulestring

Google 的位置值，保持 w+ 格式，即排名追踪工具为每个地点保存的值，原样发送给 Google。

payload.limitinteger

返回的地点数，1 到 100，默认 20（Google 列表的一页）。

payload.countrystring

提问所在市场的两位国家代码，例如 US、KR、JP。默认 US。

webhook.urlstring

你服务器上的 HTTPS 地址。任务完成后立即把结果推送到这里。

响应

完成的任务如下所示，已截取部分内容。

{
  "success": true,
  "task": {
    "id": "…",
    "taskType": "GOOGLE_PLACES",
    "status": "COMPLETED",
    "createdAt": "…"
  },
  "credits": { "creditsToCharge": 5, "creditsCharged": 5 },
  "response": {
    "places": [
      {
        "name": "Joey Gilbert Law",
        "position": 1,
        "placeId": "ChIJcW7HSupAmYARRnrM6Ap0UtU",
        "location": {
          "address": "405 Marsh Ave, Reno, NV 89509",
          "latitude": 39.519216,
          "longitude": -119.815709
        },
        "phoneNumber": "(775) 210-1501",
        "url": "https://joeygilbertlaw.com/",
        "mapsUrl": "https://maps.google.com/?cid=15371476068373133894",
        "reviews": [
          { "rating": 4.4, "count": 381, "providerName": "Google" }
        ],
        "category": "Criminal justice attorney",
        "snippet": "Joey is knowledgeable, straightforward, and fights hard for his clients.",
        "page": 1
      },
      {
        "name": "Viloria, Oliphant, Oster & Aman L.L.P.",
        "position": 2,
        "placeId": "ChIJv8KkdMlAmYARmINKFMPLxbs",
        "location": {
          "address": "327 California Ave, Reno, NV 89509",
          "latitude": 39.520335,
          "longitude": -119.81519
        },
        "phoneNumber": "(775) 515-8480",
        "url": "https://www.renonvlaw.com/",
        "mapsUrl": "https://maps.google.com/?cid=13530444694224012184",
        "reviews": [
          { "rating": 4.6, "count": 117, "providerName": "Google" }
        ],
        "category": "Personal injury attorney",
        "snippet": "Tom’s work ethic and knowledge of the legal system is beyond reproach.",
        "page": 1
      },
      "…"
    ],
    "pages": 5,
    "city": "Reno, Nevada, United States"
  }
}

task.statusstring

依次为 QUEUED、PROCESSING，最终为附带回答的 COMPLETED 或附带 error 的 FAILED。

credits.creditsChargedinteger

已完成任务扣除的积分。失败的任务为 0。

response.placesarray

按 Google 顺序排列的地点：name、跨页计数的 position、所在的 page，以及 Google 显示时的 placeId、location、phoneNumber、url、mapsUrl、reviews、category 和 snippet。

response.pagesinteger

读取的页数（每页 20 个地点），1 到 5。按此页数计费。

获取结果

请求会立即返回 status 为 QUEUED 的任务。用 GET /v1/async/task/{id} 轮询，直到 status 变为 COMPLETED 或 FAILED；或者加上 webhook.url，在服务器上接收同样的 task、credits 和 response。任务结束后，结果保留 24 小时供查询。

curl https://api.querying.ai/v1/async/task/$TASK_ID \
  -H "Authorization: Bearer $QUERYING_API_KEY"

错误

VALIDATION_ERRORHTTP 422

limit 不在 1 到 100 之间、city 为空或超过 100 个字符，或者 city 与 uule 或 location 一起发送。details 会指明该字段。

MISSING_API_KEYHTTP 401

缺少 Authorization 请求头，或密钥有误、已过期或已吊销。

INSUFFICIENT_CREDITSHTTP 402

余额低于任务价格。充值积分或升级套餐后再发送。

价格

每读取一页 20 个地点消耗 1 积分，因此 100 个地点消耗 5 积分。提交时预留 limit 所需的积分，完成时按读取的页数扣除：在第 2 页结束的列表消耗 2 积分。