> ## Documentation Index > Fetch the complete documentation index at: https://aisa.one/docs/llms.txt > Use this file to discover all available pages before exploring further. # 实时 Google 酒店搜索任务 > 酒店搜索 API 提供包含 Google Hotels 上所列不同酒店相关信息的结果。 ## OpenAPI ````yaml openapi/zh/dataforseo.json POST /dataforseo/business_data/google/hotel_searches/live openapi: 3.0.3 info: title: DataForSEO API version: 1.0.0 description: 通过 AIsa 统一网关提供的 DataForSEO API 端点。 servers: - url: https://api.aisa.one/apis/v1 security: - BearerAuth: [] paths: /dataforseo/business_data/google/hotel_searches/live: post: summary: 实时 Google 酒店搜索任务 description: >- Hotel Searches API 提供包含 Google Hotels 上所列不同酒店信息的结果。提供的结果取决于所选位置（请参阅[位置列表](https://docs.dataforseo.com/v3/business_data/google/locations.md)）和语言（请参阅[语言列表](https://docs.dataforseo.com/v3/business_data/google/languages.md)）设置。 operationId: post_dataforseo_business_data_google_hotel_searches_live requestBody: required: true content: application/json: schema: type: object properties: keyword: type: string description: >- *keyword* 可选字段，您指定的关键词用于搜索酒店列表；如果不使用此字段，我们将返回在指定位置找到的酒店列表；您可以在 `keyword` 字段中指定**最多 700 个字符**，**所有 %## 都将被解码（加号字符“+”将被解码为空格字符）**；如果需要在 `keyword` 中使用“%”字符，请将其指定为“%25”；**注意：**为获得准确的搜索结果，位置名称会自动附加到关键词中。有关 DataForSEO API 中 `keyword` 和 `keywords` 字段的规则与限制，请参阅这篇[帮助中心文章](https://dataforseo.com/help-center/rules-and-limitations-of-keyword-and-keywords-fields-in-dataforseo-apis) location_name: type: string description: >- *搜索引擎位置的完整名称*。**如果未指定 `location_code` 或 `location_coordinate`，则为必填字段**。**如果使用此字段，则无需指定 `location_code` 或 `location_coordinate`**。可以通过向 `https://api.dataforseo.com/v3/business_data/google/locations` 单独发起请求，获取包含 `location_name` 的可用位置列表。示例：`London,England,United Kingdom`。**注意：**为获得准确的搜索结果，您指定的 `location_name` 将自动附加到关键词中 location_code: type: integer description: >- *搜索引擎位置代码* **如果未指定 `location_name` 或 `location_coordinate`，则为必填字段** **如果使用此字段，则无需指定 `location_name` 或 `location_coordinate`** 可通过向 `https://api.dataforseo.com/v3/business_data/google/locations` 单独发送请求，获取包含 `location_code` 的可用位置列表。示例：`2840` location_coordinate: type: string description: >- *位置的 GPS 坐标* **如果未指定 `location_name` 或 `location_code`，则此字段为必填字段** **如果使用此字段，则无需指定 `location_name` 或 `location_code`** `location_coordinate` 参数应采用 *“纬度,经度”* 格式 *“纬度”* 和 *“经度”* 的最大小数位数：7 **注意**：如果使用坐标设置位置，搜索将在最近的居民点进行 示例：`53.476225,-2.243572` language_name: type: string description: >- *搜索引擎语言的完整名称* **如果未指定 `language_code`，则为必填字段** **如果使用此字段，则无需指定 `language_code`** 您可以通过向 `https://api.dataforseo.com/v3/business_data/google/languages` 单独发送请求，获取包含 `language_name` 的可用语言列表。示例：`English` language_code: type: string description: >- *搜索引擎语言代码* **如果未指定 `language_name`，则为必填字段** **如果使用此字段，则无需指定 `language_name`** 可通过向 `https://api.dataforseo.com/v3/business_data/google/languages` 单独发送请求，获取可用语言及其 `language_code` 的列表 示例：`en` depth: type: integer description: >- *解析深度* 可选字段 Google Hotels 中的结果数量 默认值：`20` 条自然搜索结果 最大值：`140` **注意：**无论响应中是否包含付费列表，您的账户都将按每 20 条自然搜索结果计费；因此，如果 Google Hotels 返回超过 20 条结果，将深度设置为高于 `20` 可能产生额外费用；如果指定的深度高于响应中的结果数量，差额将自动退还至您的账户余额 check_in: type: string description: >- *入住日期* 可选字段 如果未指定此字段，默认使用明天的日期；日期格式：`"yyyy-mm-dd"` 示例：`"2019-01-15"` **注意：**该值不能早于今天的日期 check_out: type: string description: >- *退房日期*；可选字段；如果未指定此字段，系统将默认使用从现在起两天后的日期；日期格式：`"yyyy-mm-dd"`；示例：`"2019-01-15"`；**注意：**该值不能小于或等于 `check_in`；`check_in` 与 `check_out` 值之间的范围不能超过 30 天 currency: type: string description: '*货币* 可选字段示例：`"USD"`' adults: type: integer description: >- *成人人数*，可选字段；如果未指定此字段，将应用默认值 `2`；**注意**，成人和儿童合计最多可指定 6 人；示例：`1` children: type: array items: type: string description: >- *儿童人数和年龄*。可选字段。如果不指定此字段，搜索中将不包含儿童；儿童年龄范围为 `0` 至 `17`；**注意**，成人和儿童合计最多可指定 6 人。如果要包含一名 14 岁儿童，请设置以下值：`[14]`；如果要包含一名 13 岁儿童和一名 8 岁儿童，请设置以下值：`[13,8]` stars: type: array items: type: string description: '*酒店星级* 可选字段；如果只想获取五星级酒店列表，请将此字段设置为 `[5]`，例如：`[3,4,5]`' min_rating: type: number description: '*最低评分* 可选字段；您可以使用此字段指定高于某个值的住客评分，例如：`2.5`' sort_by: type: string description: >- *结果排序参数* 可选字段。您可以使用此字段对结果进行排序。可选排序类型：`relevance` – 按相关性从高到低排序；`lowest_price` – 按价格从低到高排序；`highest_rating` – 按评分从高到低排序；`most_reviewed` – 按评论数量从多到少排序。默认值：`relevance` min_price: type: integer description: '*每晚最低价格* 可选字段，此值的货币取决于 `currency` 字段；示例：`100`' max_price: type: integer description: '*每晚最高价格* 可选字段，此值的货币取决于 `currency` 字段，例如：`600`' free_cancellation: type: boolean description: >- *可免费取消的酒店*，可选字段。如果希望获取可免费取消预订的酒店列表，请将此字段设置为 `true`。默认值：`false` is_vacation_rentals: type: boolean description: >- *搜索度假租赁住宿* 可选字段；如果希望获取度假租赁住宿列表而非酒店列表，请将此字段设置为 `true`；默认值：`false`。 amenities: type: array items: type: string description: >- *酒店设施*。可选字段。可使用此字段指定不同的酒店设施。示例：` [ "free_parking", "pets_allowed" ]`。可用值：`"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"` tag: type: string description: >- *用户定义的任务标识符*，可选字段，*字符数上限为 255*。你可以使用此参数标识任务并将其与结果匹配；你可以在响应的 `data` 对象中找到指定的 `tag` 值 required: - location_name - location_code - location_coordinate - language_name - language_code responses: '200': description: 成功响应 content: application/json: schema: type: object properties: version: type: string description: '*API 的当前版本*' version.status_code: type: integer description: >- *常规状态代码* 您可以在[此处](https://docs.dataforseo.com/v3/appendix/errors.md)查看完整的响应代码列表。**注意：**我们强烈建议设计必要的系统来处理相关异常或错误情况 version.status_message: type: string description: >- *一般信息消息* 你可以在[此处](https://docs.dataforseo.com/v3/appendix/errors.md)查看一般信息消息的完整列表 version.time: type: string description: '*执行时间（秒）*' version.cost: type: number description: '*任务总成本（美元）*' version.tasks_count: type: integer description: '***`tasks`**数组中的任务数量*' version.tasks_error: type: integer description: '*返回的 **`tasks`** 数组中发生错误的任务数量*' tasks: type: array items: type: string description: '*任务数组*' tasks.id: type: string description: >- 我们系统中的*唯一任务标识符*，采用[通用唯一标识符 (UUID)](https://en.wikipedia.org/wiki/Universally_unique_identifier) 格式 tasks.status_code: type: integer description: DataForSEO 生成的*任务状态码*；取值范围为：10000-60000 tasks.status_message: type: string description: '*任务信息消息*' tasks.time: type: string description: '*执行时间（秒）*' tasks.cost: type: number description: '*任务成本（美元）*' tasks.result_count: type: integer description: '*`result` 数组中的元素数量*' tasks.path: type: array items: type: string description: '*URL 路径*' tasks.data: type: object description: '*包含与您在 POST 请求中指定的参数相同的参数*' result: type: array items: type: string description: '*结果数组*' result.keyword: type: string description: >- *在 POST 数组中接收的 keyword* **返回的 keyword 会对 %## 进行解码（加号字符“+”将被解码为空格字符）** result.location_code: type: integer description: '*POST 数组中的位置代码*' result.language_code: type: string description: '*POST 数组中的语言代码*' result.check_url: type: string description: '*搜索引擎结果的直接 URL*，你可以使用它确认我们提供的结果是否准确' result.datetime: type: string description: >- *收到结果的日期和时间*，采用 UTC 格式：“yyyy-mm-dd hh-mm-ss +00:00”；示例：`2019-11-15 12:57:46 +00:00` result.items_count: type: integer description: '*项目类型* `items` 数组中的项目数量' items: type: array items: type: string description: >- *出现的项目类型* `items` 数组中出现的搜索引擎结果类型；可能的项目类型：`hotel_search_item` items.type: type: string description: '*元素类型 = **‘hotel\_search\_item’***' items.hotel_identifier: type: string description: '*Google 搜索中酒店实体的唯一标识符* 示例：`CgoI-KWyzenM_MV3EAE`' items.title: type: string description: '*酒店名称*' items.stars: type: integer description: '*酒店星级评分* 范围为 1–5 星的星级评分' items.is_paid: type: boolean description: >- *表示付费酒店列表* 如果为 `true`，相关 `hotel_search_item` 为付费广告；如果为 `false`，相关 `hotel_search_item` 为自然酒店列表 items.location: type: object description: '*酒店位置的 GPS 坐标*' items.latitude: type: number description: '*酒店在 google maps 中的纬度坐标* 示例：`"latitude": 51.584091`' items.longitude: type: number description: >- *酒店在 Google Maps 中的经度坐标* 示例：`"longitude": -0.31365919999999997` items.reviews: type: object description: '*酒店评论和评分信息*' items.value: type: number description: '*基于所有评论的平均评分*' items.votes_count: type: integer description: '*投票数*' items.mentions: type: array items: type: string description: >- *酒店提及信息* **注意：**此字段始终等于 `null`；可使用此字段简化集成，并确保与 [Hotel Info](https://docs.dataforseo.com/v3/business_data/google/hotel_info/live/advanced.md) 端点的互操作性 items.rating_distribution: type: object description: >- *按投票统计的评分分布* **注意：** 此字段始终等于 `null`；使用此字段可简化集成，并确保与 [酒店信息](https://docs.dataforseo.com/v3/business_data/google/hotel_info/live/advanced.md) 端点的互操作性 items.other_sites_reviews: type: array items: type: string description: >- *第三方网站上的评价* **注意：**此字段始终等于 `null`；使用此字段可简化集成，并确保与 [Hotel Info](https://docs.dataforseo.com/v3/business_data/google/hotel_info/live/advanced.md) 端点的互操作性 items.overview_images: type: array items: type: string description: '*酒店的精选图片*' items.prices: type: object description: '*酒店价格*' items.price: type: integer description: '*每晚价格*' items.price_without_discount: type: integer description: '*未应用折扣的每晚全价*' items.currency: type: string description: 除非在 POST 数组中指定，否则默认采用*价格货币* `USD` items.discount_text: type: string description: '*有关已应用折扣的文本*' items.check_in: type: string description: >- UTC 格式的*入住日期和时间*：“yyyy-mm-dd hh-mm-ss +00:00”，示例：`2019-11-15 12:57:46 +00:00` items.check_out: type: string description: >- UTC 格式的*退房日期和时间*：“yyyy-mm-dd hh-mm-ss +00:00”，示例：`2019-11-15 12:57:46 +00:00` items.visitors: type: integer description: '*此价格对应的酒店访客人数*' items.items: type: array items: type: string description: >- *项目数组* **注意：**此字段始终等于 `null`；使用此字段可简化集成，并确保与 [Hotel Info](https://docs.dataforseo.com/v3/business_data/google/hotel_info/live/advanced.md) 端点的互操作性 '400': description: 错误请求 '401': description: 未授权 '429': description: 超出速率限制 '500': description: 内部服务器错误 components: securitySchemes: BearerAuth: type: http scheme: bearer ````