获取 Google店搜索已完成任务

GET /v3/business_data/google/hotel_searches/tasks_ready

本接口使用 GET 方法，路径为：

/v3/business_data/google/hotel_searches/tasks_ready

用于获取已完成但尚未提取结果的搜索任务列表。调用本接口后，可获得已完成任务的 id，再通过任务结果接口获取数据。

如果创建任务时了 postback_url，通常无需轮询本接口。对于每分钟需要收集 1000 个任务的高并发场景，建议优使用回调机制；本接口可用于补偿获取回调失败的任务 ID。

请求地址

获取 Google店搜索任务

GET https://api.seermartech.cn/v3/business_data/google/hotel_searches/tasks_ready

按搜索引擎获取已完成任务

将 $se 替换为搜索引擎名称：

GET https://api.seermartech.cn/v3/business_data/$se/tasks_ready

获取 Business Data API 的已完成任务

GET https://api.seermartech.cn/v3/business_data/tasks_ready

容路径

以下路径为容调用路径：

GET https://api.seermartech.cn/v3/business_data/wp/hotel_searches/tasks_ready

认证

请求头中使用以下认证方式：

Authorization: Bearer smt_live_YOUR_KEY
Content-Type: application/json

计费与限制

• 获取已完成任务列表不产生额外费用。
• 每个任务会一直保留在列表中，直到被成功获取。
• 每分钟最多调用 20 次。
• 每次调用最多返回 1000 个任务。
• 返回范围为最近 3 天完成且尚未被获取的任务。
• 已经获取过的任务不会再次出现在列表中。
• 完成 3 天仍未获取的任务将从列表中移除。
• 如果任务了 postback_url，任务通常不会出现在本列表中。
• 只有当回调请求失败，且业务服务器返回的 HTTP 状态码小于 200 或大于 300 时，该任务才可能重新出现在列表中。

本接口本身不收取任务结果获取费用；如涉及接口的扣费，以响应头 X-SeerMarTech-Charge-CNY 为准。

响应结构

接口返回 JSON 格式数据 tasks 数组。

顶层字段

字段	类型	说明
version	string	当前 API 版本
status_code	integer	请求的通用状态码
status_message	string	请求的通用说明信息
time	string	请求执行耗时，单位为秒
cost	float	平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
tasks_count	integer	tasks 数组中的任务数量
tasks_error	integer	tasks 数组中返回错误的任务数量
tasks	array	已完成任务列表

完整状态码和错误码请参考错误码文档。建议客户端对异常状态和错误响应进行统一处理。

tasks 数组中的任务字段

字段	类型	说明
id	string	任务唯一标识，采用 UUID 格式
status_code	integer	任务状态码，取值范围为 10000-60000
status_message	string	任务状态说明
time	string	任务执行耗时，单位为秒
cost	float	平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
result_count	integer	result 数组中的数量
path	array	任务结果路径信息
data	object	创建任务时传的请求参数
result	array	已完成任务的结果信息

tasks[].result 字段

字段	类型	说明
id	string	已完成任务的唯一标识，采用 UUID 格式
se	string	创建任务时指定的搜索引擎，当前支持 google
se_type	string	搜索引擎类型
date_posted	string	任务提交时间，使用 UTC 格式
tag	string	用户自定义任务标识
endpoint	string	用于获取任务结果的 URL 路径

请求示例

cURL

curl --location --request GET \
  "https://api.seermartech.cn/v3/business_data/google/hotel_searches/tasks_ready" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json"

Python

import requests

url = "https://api.seermartech.cn/v3/business_data/google/hotel_searches/tasks_ready"

headers = {
    "Authorization": "Bearer smt_live_YOUR_KEY",
    "Content-Type": "application/json",
}

response = requests.get(url, headers=headers)

if response.status_code == 200:
    result = response.json()
    if result.get("status_code") == 20000:
        print(result)
        # 在此处理已完成任务列表
    else:
        print(
            "API 错误：代码=%s，消息=%s"
            % (result.get("status_code"), result.get("status_message"))
        )
else:
    print("HTTP 错误：", response.status_code)

TypeScript

import axios from "axios";

axios
  .get(
    "https://api.seermartech.cn/v3/business_data/google/hotel_searches/tasks_ready",
    {
      headers: {
        Authorization: "Bearer smt_live_YOUR_KEY",
        "Content-Type": "application/json",
      },
    }
  )
  .then((response) => {
    const result = response.data;

    if (result.status_code === 20000) {
      console.log(result);
      // 在此处理已完成任务列表
    } else {
      console.error(
        `API 错误：代码=${result.status_code}，消息=${result.status_message}`
      );
    }
  })
  .catch((error) => {
    console.error("请求失败：", error.message);
  });

响应示例

{
  "version": "0.1.20210430",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.1465 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": " ಮೂಲಕ-task-uuid",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.1200 sec.",
      "cost": 0,
      "result_count": 1,
      "path": [
        "v3",
        "business_data",
        "google",
        "hotel_searches",
        "tasks_ready"
      ],
      "data": {
        "se_type": "hotels",
        "se": "google",
        "api": "business_data",
        "function": "hotel_searches"
      },
      "result": [
        {
          "id": "task-uuid",
          "se": "google",
          "se_type": "hotels",
          "date_posted": "2024-01-01 12:00:00 +00:00",
          "tag": "hotel-search-task",
          "endpoint": "/v3/business_data/google/hotel_searches/task_get"
        }
      ]
    }
  ]
}

> id、时间、路径和任务结果作结构示例，值以接口返回为准。

使用流程

1. 创建搜索任务并记录任务 ID。
2. 通过回调机制或本接口确认任务已完成。
3. 从 tasks[].result[].id 获取已完成任务 ID。
4. 使用响应中的 endpoint 或对应的任务结果接口获取详细结果。
5. 成功获取后，任务将从已完成任务列表中移除。

实用场景

• 轮询已完成的搜索任务，批量发现可获取结果的任务，降低逐个查询任务状态的请求开销。
• 补偿回调失败的任务，通过任务列表找回未成功推送到业务系统的任务，数据丢失。
• 构建任务调度队列，任务完成状态批量拉取结果，提高价格、评分和房源信息的处理效率。
• 理过期任务，监控 3 天仍未收集的任务，及时调整结果消费和数据库流程。
• 统计任务完成，结合 tasks_count、tasks_error 和任务状态码分析搜索任务的成功率与异常类型。