创建 Google店搜索任务

接口说明

该接口用于提交 Google店搜索任务。任务完成后，可基于返回的任务 id 获取结果；也可以在创建任务时 postback_url 或 pingback_url，由本平台在任务完成后主动通知。

返回结果会结合以下条件生成：

搜索 keyword
地理位置 location_name / location_code / location_coordinate
语言 language_name / language_code

接口路径：

POST https://api.seermartech.cn/v3/business_data/google/hotel_searches/task_post

计费与调用限制

创建任务即产生扣费
实扣费以响应头 X-SeerMarTech-Charge-CNY 为准
响应中的 cost 为平台 USD 计价；如按换算口径估算，示例响应 0.00075 USD 约合 ¥0.0120 / 次
每分钟最多可发起 2000 次 API 调用
单次 POST 请求最多提交 100 个任务
如果单次请求 100 个任务，出部分会返回错误 40006

异步回调说明

任务提交成功后，你可以通过以下方式获取结果：

使用任务 id 查询已完成任务结果
创建任务时传 postback_url，任务完成后本平台会向该地址发送结果的 POST 请求，数据采用 gzip 压缩
创建任务时传 pingback_url，任务完成后本平台会向该地址发送 GET 通知

注意事项：

如果你的服务器在 10 秒未响应，连接会因时被中止 -时后，任务会被转 /v3/business_data/google/hotel_searches/tasks_ready/ 列表
回调 URL 中可使用 $id 和 $tag 变量，本平台会在发送前替换为真实值
postback_url 和 pingback_url 中的特殊字符会进行 URL 编码，例如 # 会被编码为 %23

请求体格式

所有 POST 数据使用 UTF-8 编码的 JSON，且请求体为 JSON 数组格式：

json

[
 {
 "location_name": "New York,New York,United States",
 "language_name": "English",
 "keyword": "cheap hotel"
 }
]

请求参数

字段	类型	说明
`keyword`	string	可选。用于搜索列表的；不传时，将返回指定位置下找到的列表。最长 700 个字符。`%##` 会被解码，`+` 会被解码为空格；如需传 `%`，请使用 `%25`。为提高结果准确性，系统会自动将位置名称附加到后。
`priority`	integer	可选。任务优级。`1` = 普通优级（默认）；`2` = 高优级。高优级会产生额外费用，扣费以响应头 `X-SeerMarTech-Charge-CNY` 为准。
`location_name`	string	当未传 `location_code` 或 `location_coordinate` 时填。搜索位置名。传此字段时无需再传 `location_code` 或 `location_coordinate`。示例：`London,England,United Kingdom`。可通过 `/v3/business_data/google/locations` 获取可用位置列表。
`location_code`	integer	当未传 `location_name` 或 `location_coordinate` 时填。搜索位置编码。传此字段时无需再传 `location_name` 或 `location_coordinate`。示例：`2840`。可通过 `/v3/business_data/google/locations` 获取。
`location_coordinate`	string	当未传 `location_name` 或 `location_code` 时填。GPS 坐标，格式为 `"latitude,longitude"`，纬度和经度最多 7 位小数。示例：`53.476225,-2.243572`。若使用坐标，搜索会在最近的定点进行。
`search_this_area`	boolean	可选。是否展示当前地图区域的。可选值：`true`、`false`，默认 `true`。若设为 `false`，将该模式，且搜索时不会把 `location_name` 自动附加到 `keyword`。
`language_name`	string	当未传 `language_code` 时填。搜索语言名。传此字段时无需再传 `language_code`。示例：`English`。可通过 `/v3/business_data/google/languages` 获取。
`language_code`	string	当未传 `language_name` 时填。搜索语言编码。传此字段时无需再传 `language_name`。示例：`en`。可通过 `/v3/business_data/google/languages` 获取。
`depth`	integer	可选。抓取深度，即 Google Hotels 结果数量。默认 `18`，最大 `140`。每 `18` 条自然结果计费一次，不受响应中广告结果数量影响；若设置大于 `18` 且返回 `18` 条，可能产生额外费用；若设置值高于结果数，差额会自动返还。
`check_in`	string	可选。日期，格式 `"yyyy-mm-dd"`。默认值为明天。日期不能早于今天。示例：`"2019-01-15"`
`check_out`	string	可选。退房日期，格式 `"yyyy-mm-dd"`。默认值为后天。晚于 `check_in`，且与 `check_in` 的间隔不能 30 天。
`currency`	string	可选。币种。示例：`"USD"`
`adults`	integer	可选。成人数量，默认 `2`。成人与儿童总人数最多 `6` 人。示例：`1`
`children`	array	可选。儿童年龄数组；不传则不儿童。每个表示一名儿童年龄，范围 `0` 到 `17`。成人与儿童总人数最多 `6` 人。例如：一个 14 岁儿童可传 `[14]`；一个 13 岁和一个 8 岁儿童可传 `[13, 8]`。
`stars`	array	可选。星级筛选。例如查询五星可传 `[5]`。
`min_rating`	float	可选。最小住客评分。例如：`2.5`
`sort_by`	string	可选。结果排序方式。可选值：`relevance`（性，默认）、`lowest_price`（最低价格）、`highest_rating`（最高评分）、`most_reviewed`（评论最多）。
`min_price`	integer	可选。每晚最低价格，币种取决于 `currency`。示例：`100`
`max_price`	integer	可选。每晚最高价格，币种取决于 `currency`。示例：`600`
`free_cancellation`	boolean	可选。是否返回支持取消的。设为 `true` 时启用。默认 `false`。
`is_vacation_rentals`	boolean	可选。是否搜索度假租赁而非。设为 `true` 时启用。默认 `false`。
`amenities`	array	可选。设施筛选。可传多个设施值。支持值见下方“设施枚举”。
`tag`	string	可选。自定义任务标识，最长 255 个字符。可用于结果对账与任务追踪。返回结果中的 `data` 对象会该值。
`postback_url`	string	可选。任务完成后接收结果的回调地址。本平台会向该地址发送 gzip 压缩的 `POST` 请求。支持 `$id` 和 `$tag` 占位符。示例：`http://your-server.com/postbackscript?id=$id`
`pingback_url`	string	可选。任务完成通知地址。本平台会向该地址发送 `GET` 请求。支持 `$id` 和 `$tag` 占位符。示例：`http://your-server.com/pingscript?id=$id&tag=$tag`

amenities 可选值

text

air_conditioning
all_inclusive_available
bar
free_breakfast
fitness_center
kid_friendly
free_parking
pets_allowed
pool
restaurant
room_service
spa
free_wifi
parking
indoor_pool
outdoor_pool
wheelchair_accessible
beach_access

响应结构

接口返回 JSON 数据， tasks 数组。

顶层字段

字段	类型	说明
`version`	string	当前 API 版本
`status_code`	integer	局状态码，完整列表参考 `/v3/appendix/errors`
`status_message`	string	局状态信息
`time`	string	执行耗时，单位秒
`cost`	float	本次请求总费用，单位为平台 USD
`tasks_count`	integer	`tasks` 数组中的任务数
`tasks_error`	integer	`tasks` 数组中报错的任务数
`tasks`	array	任务数组

tasks 数组中的字段

字段	类型	说明
`id`	string	平台唯一任务 ID，UUID 格式
`status_code`	integer	任务状态码，范围通常为 `10000-60000`
`status_message`	string	任务状态信息
`time`	string	任务执行耗时
`cost`	float	单个任务费用，单位为平台 USD
`result_count`	integer	`result` 数组中的数量
`path`	array	URL 路径
`data`	object	与提交时传参数一致的数据对象
`result`	array	结果数组；该接口为创建任务接口，此处通常为 `null`

请求示例

cURL

bash

curl --location --request POST "https://api.seermartech.cn/v3/business_data/google/hotel_searches/task_post" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "location_name": "New York,New York,United States",
 "language_name": "English",
 "keyword": "cheap hotel",
 "check_in": "2023-06-01",
 "check_out": "2023-06-30",
 "currency": "USD",
 "adults": 2,
 "children": [13, 8],
 "sort_by": "highest_rating",
 "priority": 2,
 "tag": "example"
 }
]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/business_data/google/hotel_searches/task_post"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}

payload = [
 {
 # 示例 1：最简任务
 "location_code": 1023191,
 "language_code": "en",
 "keyword": "cheap hotel"
 },
 {
 # 示例 2：带更多筛选条件的任务
 "location_name": "New York,New York,United States",
 "language_name": "English",
 "keyword": "cheap hotel",
 "check_in": "2023-06-01",
 "check_out": "2023-06-30",
 "currency": "USD",
 "adults": 2,
 "children": [13, 8],
 "sort_by": "highest_rating",
 "priority": 2,
 "tag": "example",
 "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
 }
]

response = requests.post(url, headers=headers, json=payload)
print(response.json)

TypeScript

typescript

import axios from "axios";

const postArray = [
 {
 location_name: "New York,New York,United States",
 language_name: "English",
 keyword: "cheap hotel",
 check_in: "2023-06-01",
 check_out: "2023-06-30",
 currency: "USD",
 adults: 2,
 children: [13, 8],
 sort_by: "highest_rating",
 pingback_url: "https://your-server.com/pingscript?id=$id&tag=$tag",
 priority: 2,
 tag: "example"
 }
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/business_data/google/hotel_searches/task_post",
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
 },
 data: postArray
})
 .then((response) => {
 // 输出响应结果
 console.log(response.data);
 })
 .catch((error) => {
 console.error(error);
 });

响应示例

json

{
 "version": "0.1.20220720",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.1620 sec.",
 "cost": 0.00075,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "6f3b8c1e-5a3d-4f5b-9b4b-1234567890ab",
 "status_code": 20100,
 "status_message": "Task Created.",
 "time": "0.0210 sec.",
 "cost": 0.00075,
 "result_count": 0,
 "path": [
 "v3",
 "business_data",
 "google",
 "hotel_searches",
 "task_post"
 ],
 "data": {
 "api": "business_data",
 "function": "hotel_searches",
 "se": "google",
 "language_code": "en",
 "location_name": "New York,New York,United States",
 "keyword": "cheap hotel",
 "check_in": "2023-06-01",
 "check_out": "2023-06-30",
 "currency": "USD",
 "adults": 2,
 "children": [13, 8],
 "sort_by": "highest_rating",
 "tag": "example",
 "se_type": "hotels",
 "device": "desktop",
 "os": "windows"
 },
 "result": null
 }
 ]
}

状态码与错误处理

顶层 status_code = 20000 通常表示请求成功
任务创建成功时，任务级别通常会返回 20100
如果单次 POST 请求中任务数量 100，出部分会返回 40006
建议同时检查：
顶层 status_code
tasks_error
每个任务的 status_code 与 status_message

完整错误码可参考 /v3/appendix/errors。

使用说明补

位置参数三选一

以下三个字段至少传一个，且通常只传一个：

location_name
location_code
location_coordinate

语言参数二选一

以下两个字段至少传一个：

language_name
language_code

与位置拼接规则

为提高搜索准确性，系统通常会把位置名称自动附加到 keyword 后进行查询。但当 search_this_area=false 时，不会追加 location_name。

###住与退房日期规则

check_in 不能早于今天
check_out须晚于 check_in -住和退房间隔不能 30 天

人数限制

adults + children.length <= 6
children 中每个年龄值在 0 到 17 之间

实用场景

监控热门目的地供给，按城市、语言和日期批量抓取列表，评估不同区域的覆盖度与竞争强度
筛选高评分低价，通过 min_rating、max_price、sort_by 组合条件，快速发现高性价比资源
对比不同日期价格，批量提交多个 check_in/check_out 任务，分析节假日或旺季期间的价格波动
挖掘细分住宿需求，结合 amenities、free_cancellation、stars 等条件，识别亲子、商务、宠物友好等场景的供给
追踪度假租赁市场，将 is_vacation_rentals 设为 true，对比与民宿类房源在不同区域的可见度与价格分布

创建 Google店搜索任务 ​

接口说明 ​

计费与调用限制 ​

异步回调说明 ​

请求体格式 ​

请求参数 ​

amenities 可选值 ​

响应结构 ​

顶层字段 ​

tasks 数组中的字段 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应示例 ​

状态码与错误处理 ​

使用说明补 ​

位置参数三选一 ​

语言参数二选一 ​

与位置拼接规则 ​

人数限制 ​

实用场景 ​