猫途鹰酒店图片和设施 API:解析 photos 与 amenitiesScreen

发布于 2026年10月28日

data.photos 是数组,data.amenitiesScreen 也是数组。猫途鹰酒店详情接口 get-hotel-details 的 data 对象里,已保存的成功调用能确认的就是这两个字段,类型都是数组。数组里有几项、每一项叫什么字段、是不是这家酒店的全部图片和设施,样本都没有回答。

这决定了接入方式。做酒店详情面板时,很多人先假设一份平铺的酒店记录,直接写 hotel["images"][0]["url"]、hotel["wifi"],字段名全凭印象。本文换一种读法:沿着地点联想、酒店列表、酒店详情三层响应,逐层确认容器在哪里,再决定哪些字段可以进页面。

酒店图片与设施入口:data.photos 和 data.amenitiesScreen

已保存的详情调用返回 HTTP 200,JSON 对象含布尔 status=true、字符串 message、整数 timestamp 和对象 data;data 里是 photos 与 amenitiesScreen 两个数组。必填参数是酒店 id、checkIn 和 checkOut,日期格式 YYYY-MM-DD。请求形式如下:第一行用的是已观察过的地名 New York,第二行是模板,HOTEL_ID 要来自后面讲的酒店列表。

https://api.opendata-api.com/api/project/tripadvisor-data/search-location?key=YOUR_API_KEY&query=New%20York
https://api.opendata-api.com/api/project/tripadvisor-data/get-hotel-details?key=YOUR_API_KEY&id=HOTEL_ID&checkIn=YYYY-MM-DD&checkOut=YYYY-MM-DD

平台授权密钥在控制台创建,只放在服务端环境变量里。它直接出现在查询串中,所以浏览器不要直连,访问日志和代理日志也要脱敏。YOUR_API_KEY 不是可用凭据,阅读或复制示例都不会发出请求。

接入第一天先不写渲染,写一个只输出结构的诊断函数:容器在哪、是什么类型、有几项、第一项有哪些键。它不保存也不打印图片链接。

import os
import requests

BASE = "https://api.opendata-api.com/api/project/tripadvisor-data"

def call(operation_id, **params):
    # Keep the platform key on the server side only.
    params["key"] = os.environ["PLATFORM_API_KEY"]
    resp = requests.get(f"{BASE}/{operation_id}", params=params, timeout=30)
    resp.raise_for_status()  # transport layer first
    return resp.json()

def describe(value):
    if isinstance(value, list):
        first = value[0] if value else None
        shape = sorted(first) if isinstance(first, dict) else type(first).__name__
        return f"list[{len(value)}] first={shape}"
    return type(value).__name__

def diagnose_detail(body):
    data = body.get("data")
    if not isinstance(data, dict):
        return {"status": body.get("status"), "data": describe(data)}
    return {
        "status": body.get("status"),
        "dataKeys": sorted(data),
        "photos": describe(data.get("photos")),
        "amenitiesScreen": describe(data.get("amenitiesScreen")),
    }

城市 geoId 不是酒店详情接口的 id

详情请求要的 id 不来自地点联想。search-location 只做一件事:把用户输入的城市或地名解析成候选地点。必填参数是 query;New York 的成功实测里,data 直接就是地点对象数组,不是 data.data。文档声明的字段是字符串 documentId、secondaryText、title、trackingItems,实测还多了整数 geoId。这些字段都可能缺,空数组也是合法结果。

用 title 和 secondaryText 让用户区分同名地点,不要默默取第一条。文档示例里的 title 带类似加粗标签的 HTML 标记,渲染时按纯文本处理或先净化。选定之后把 geoId 存成整数,请求时再转成字符串,传给 search-hotels 和 get-hotels-filter,这两个接口的 geoId 都按字符串声明,文档也明确说不能拿酒店标识顶替。

def destination_choices(body):
    rows = body.get("data")
    if not isinstance(rows, list):
        raise ValueError("search-location: data is not a list")
    choices = []
    for row in rows:
        geo_id = row.get("geoId") if isinstance(row, dict) else None
        if type(geo_id) is int:
            choices.append({
                "geoId": geo_id,
                "title": row.get("title"),
                "secondaryText": row.get("secondaryText"),
            })
    return choices  # let the user pick; never take choices[0] silently

geoId 和酒店 id 都是看起来像数字的标识,传错时单看语法分不出来,所以数据模型里要拆成 destination.geoId 与 hotel.id 两个字段。想按坐标找附近酒店,用 search-hotels-by-location:它要字符串 latitude、longitude,不要 geoId。这条路由没有已保存的响应样本,列表结构必须先诊断,不要直接套用 data.data。

地点数组、data.data 酒店列表与详情对象要分开解析

同一条链路里,三个响应的容器位置各不相同:

请求读哪里已保存样本能确认什么
search-locationbody.data地点对象数组
search-hotelsbody.data.data外层 data 是对象,酒店行数组在里面一层
get-hotel-detailsbody.data.photos、body.data.amenitiesScreen两个数组,数组项内部字段未确认

所以才会有 data.data:外层 data 是整次搜索的容器对象,酒店行在它里面的 data 数组。文档没有把响应键声明为必需,因此每一层都要自己检查。已保存的酒店搜索只证明 data.data 是数组;文档示例列出的行字段,如 id、title、bubbleRating、cardPhotos、priceDetails、priceForDisplay,来自被截断的示例,没有被样本确认,不能当成一定存在。pageNumber 默认是 1,总数、页大小和排序是否稳定都没有依据,别据此写“共多少家”。

HTTP 200 只说明传输成功。本项目其他路由的已保存调用里,出现过 HTTP 200 却 status=false 的结果,其中 message 还是数组而不是字符串。所以 status 必须是 True 才去读 data,message 当任意 JSON 值原样记录。若你的客户端在响应外面还看到平台的 code/message/data 外层,先确认外层成功,再把里面这层交给下面的函数。

def hotel_rows(body):
    if body.get("status") is not True:
        raise RuntimeError(f"business failure: {body.get('message')!r}")
    outer = body.get("data")
    rows = outer.get("data") if isinstance(outer, dict) else None
    if not isinstance(rows, list):
        raise ValueError("search-hotels: data.data is not a list")
    return rows  # an empty list is a valid result, not an error

def selected_hotel_id(row):
    # The documentation example names row["id"]; confirm it on a real row first.
    value = row.get("id") if isinstance(row, dict) else None
    if isinstance(value, (str, int)) and not isinstance(value, bool) and str(value).strip():
        return str(value)
    raise ValueError("row has no usable id; inspect the row before calling get-hotel-details")

第一次接入时,人工打印首行的键,确认这个 id 就是详情接口接受的酒店标识,再把选择流程自动化。

其他同类应用的 API 可通过联系页面提出需求,平台也提供私有源码部署选项。

入住离店日期、人数与币种不能在详情请求中丢失

搜索与详情是两次请求,最容易丢的是第二次。search-hotels 必填 geoId、checkIn、checkOut,可选 adults、rooms、childrenAges、currencyCode、pageNumber;get-hotel-details 必填 id、checkIn、checkOut,可选 adults、rooms、childrenAges、currency。币种参数一个叫 currencyCode,一个叫 currency。它们都是可选项,写错名字的风险是静默丢掉币种,而不一定是请求失败。

其余约定:childrenAges 是 0 到 17 的年龄数组,0 表示不满一岁,文档示例为 [0,10];数组如何编码进查询串文档没写,带孩子的请求先在自己的账号上验证,没有孩子就不传。adults 和 rooms 没有文档化默认值,不确定就留空,不要拿自己的默认人数冒充用户选择。币种代码取自 get-currency,这条路由没有已保存样本,文档示例里有 majorCurrencies 与 minorCurrencies 两个数组,条目含 code、name、symbol,代码和展示名分开存。

文档没有说明图片与设施会不会随日期、人数变化。保留同一语境的目的,是让一次详情结果能和当初那次搜索对账,而不是承诺内容会变。做法是在保存候选酒店时就存一份 Stay,两个请求都从它派生参数:

import json
from typing import NamedTuple, Optional, Tuple

class Stay(NamedTuple):
    check_in: str                      # YYYY-MM-DD
    check_out: str                     # YYYY-MM-DD
    adults: Optional[int] = None
    rooms: Optional[int] = None
    children_ages: Tuple[int, ...] = ()
    currency: Optional[str] = None     # a code taken from get-currency

    def _common(self):
        params = {"checkIn": self.check_in, "checkOut": self.check_out}
        if self.adults is not None:
            params["adults"] = self.adults
        if self.rooms is not None:
            params["rooms"] = self.rooms
        if self.children_ages:
            # Documented example form is [0,10]; verify the encoding on your account.
            params["childrenAges"] = json.dumps(list(self.children_ages), separators=(",", ":"))
        return params

    def search_params(self, geo_id, page=1):
        params = {**self._common(), "geoId": str(geo_id), "pageNumber": page}
        if self.currency:
            params["currencyCode"] = self.currency  # search names it currencyCode
        return params

    def detail_params(self, hotel_id):
        params = {**self._common(), "id": hotel_id}
        if self.currency:
            params["currency"] = self.currency  # details names it currency
        return params

amenity、brand、class、deals、healthSafety、neighborhood、style、type 这些数组筛选,可接受的取值文档都没有给出。先用 get-hotels-filter 看该目的地和日期下的筛选元数据,核对取值映射后再用;第一次对接干脆不传。

先保留数组原始项,不猜图片链接和设施名称字段

photos 和 amenitiesScreen 的数组项到底是链接字符串、带多种尺寸的对象,还是分区结构,已保存样本只证明了容器。读取层的原则因此很简单:整项原样保存,不改名、不拍平、不挑字段。渲染层再加白名单,某个字段在多家酒店的真实响应里都见过之后,才允许进入页面。

被截断的文档示例还提到 data.about(含 title、tags、content)、带 title 和 content 的设施分区,以及 data.attractionsNearby.content。样本没有确认它们,只能当待验证线索:先在诊断输出里看到,再决定用不用。图片同理,不预设 url 之类的字段名,也不预设图片数量或排序有什么含义。保存时连同酒店 id 与当时的 Stay 一起存,之后才能对得上账。

空数组、字段缺失与结构异常分别处理

对每个集合单独判定状态,并且与“请求失败”分开统计:

def collection_state(data, key):
    if not isinstance(data, dict):
        return "malformed"
    if key not in data:
        return "absent"
    value = data[key]
    if not isinstance(value, list):
        return "malformed"
    return "populated" if value else "empty"

def read_detail(body, hotel_id, stay):
    if body.get("status") is not True:
        return {"hotelId": hotel_id, "outcome": "business_failure", "message": body.get("message")}
    data = body.get("data")
    record = {"hotelId": hotel_id, "stay": stay._asdict(), "outcome": "ok"}
    for key in ("photos", "amenitiesScreen"):
        record[key] = {
            "state": collection_state(data, key),
            "items": data.get(key) if isinstance(data, dict) else None,  # raw items, untouched
        }
    return record

四种状态含义不同。populated 才进入渲染;empty 是成功返回了空数组;absent 是 data 里根本没有这个键,而文档并未把它声明为必需;malformed 是 data 或集合的类型不对,应记录并告警,不要硬转。

设施数组为空,既不能推出这家酒店没有 Wi-Fi 或泳池,也不能推出接口出了故障,它只表示这次响应没有给出条目。页面上写“暂无设施信息”,不要写“无设施”。重试也补不出不存在的内容,同一家酒店不必循环请求;做内容覆盖审计时,把四种状态各自计数,再与 HTTP 错误和 status=false 分开。

酒店内容接口不能证明可订房态或图片使用授权

get-hotel-details 是内容查询,不是预订确认。它不保证有房、价格、评论或完整的物业覆盖;search-hotels 的文档示例虽然列了价格相关字段,实测也没有给出实时价格、总数或库存的保证。要展示价格或接单,必须走你自己的预订和报价链路。设施列表同样不是穷举清单,healthSafety 之类的筛选条件,更不是酒店当前安全状况的证明。

这条链路之外的路由各有一套参数,不要照搬本文的解析方式。租车分两个接口:search-cars-same-drop-off 用于原地还车,只有 search-cars-different-drop-off 才有单独的还车地点参数;民宿的 rental-details 等四个路由都要求你已经手握 rentalId;新接入的餐厅详情从 get-restaurant-details-v2 开始,旧版只留给现有客户端。这些路由大多没有已保存的调用样本,同样要先诊断、再解析。

图片也是如此。接口返回了图片,不等于你获得了展示、转存或商用的授权。上线前要自行确认来源方的使用条款,再决定能否缓存、改尺寸、用于广告或落地页,以及署名与下架如何处理。