Trivago Accommodation Search

This API exposes **Trivago-style** travel search through a small, JSON-first surface: you get **destination suggestions** from free text, then **accommodation listings** with **normalized prices, ratings, imagery, and a best-offer snapshot**—similar to what users expect from **hotel metasearch** experiences (search many offers, compare at a glance, then leave your app via a **click-out** link to complete booking on a partner site).

原始信息汇总

Trivago Accommodation Search 数据集概述

数据集基本信息

• 数据集名称: Trivago Accommodation Search
• 类别: Travel
• 提供者: OpenFinanceApi
• 订阅者数量: 2
• 版本: 1.0.0 (current)
• 定价方案:
  • BASIC: $0.00 / mo
  • PRO: $10.00 / mo

数据集描述

此API通过一个简洁的、JSON优先的接口暴露Trivago风格的旅行搜索功能：用户可通过自由文本获取目的地建议，然后获取包含标准化价格、评分、图像和最佳优惠快照的住宿列表——类似于用户期望的酒店元搜索体验（搜索多个报价，一目了然地比较，然后通过点击跳转链接离开您的应用，在合作伙伴网站上完成预订）。

主要功能与用途

可构建的应用

• 目的地发现: 将部分文本（如“tok”、“HK island”、地标名称）转换为具有稳定id + ns、人工标签和坐标的结构化行。
• 住宿搜索与浏览: 针对选定的目的地、入住/退房日期以及成人/儿童人数，检索属性列表，包含每晚价格、格式化价格、评分/评论、标签（例如政策提示）以及突出显示交易的广告商。
• 地图引导探索: 使用建议和列表中的**latitude / longitude**来放置图钉、聚类或“搜索此视口”风格的UI。
• 比较与研究UI: 在打开合作伙伴网站之前，为决策支持呈现并排卡片（价格、评分、图像、距离）。
• 多货币显示: 以给定的**currency**（ISO代码）请求结果，使报价与钱包或区域设置保持一致。
• 自动化与内部工具: 脚本和仪表板可以为QA、价格抽查或旅行运营工作流提取结构化JSON。

典型集成用户

• 消费者旅行产品: 周末旅行规划器、城市指南和“我附近的酒店”风格应用，希望获得元搜索风格的浏览体验，而无需运营全球供应合同。
• B2B旅行与移动性: 员工旅行、活动住宿或搬迁工具，需要快速报价和用于报告的标准化JSON。
• AI助手与聊天机器人: 自然语言“在X地为我找一家低于Y美元的酒店”流程：使用search-area解析X，然后使用解析出的日期和客人信息调用search。
• 分析师与工程师: 原型、A/B测试或RapidAPI实验，其中JSON + HTTPS已足够。

数据集限制

• 不是预订引擎: 此层不提供保留、购物车或支付功能；完成操作发生在合作伙伴/广告商网站上，通过**clickoutUrl**进行。
• 不保证完整的库存馈送: 结果数量和排序遵循上游图谱；使用**limit / offset**进行分页式消费，不作为严格的SLA。
• 不是实时收益管理: 价格和可用性可能在响应后立即发生变化；当新鲜度重要时，请刷新或重新查询。

端点详情

1) 搜索目的地/POI — POST /api/trivago/search-area

• 功能: 输入提示/地点选择器后端。发送部分或完整文本；API返回排名建议。
• 请求体 (JSON):
  • query (string, 必需): 用于位置或兴趣点的关键词。
• 成功响应字段:
  • success (boolean): 此网关响应的完成标志。
  • total (integer): data中的建议数量。
  • data[] (array): 每个行是一个可选择的目的地概念。
• 每个建议 (data[] 项) 字段:
  • id, ns: 共同构成目的地键——将它们作为**destinationId和destinationNs**传递给住宿搜索。
  • name (string): 主要显示标签（例如城市或POI名称）。
  • type (string): 可用时的概念类别（有助于UI中的图标/过滤器）。
  • location (string): 更广泛的地理上下文（例如地区或国家行）。
  • latitude, longitude (number): 可选的客户端地图放置或“距我距离”排序。

2) 搜索住宿 — POST /api/trivago/search

• 功能: 旅行者选择地点和时间后的结果网格/列表/地图步骤。返回每个属性行的主要优惠快照。
• 行为说明: 服务器聚合多个内部轮次，直到搜索完成或达到内部限制。为多秒延迟和异步UX（骨架列表、进度、导航时取消）做计划。
• 请求体 (JSON):
  • destinationId (integer, 非必需): 来自search-area → id。
  • destinationNs (integer, 非必需): 来自search-area → ns。
  • arrival (string, 非必需): 入住日期，YYYY-MM-DD。
  • departure (string, 非必需): 退房日期，YYYY-MM-DD。
  • adults (integer, 非必需): 第一个房间的成人人数；如果省略，服务器可能使用默认值。
  • childrenCsv (string, 非必需): 逗号分隔的儿童年龄，例如6,9。
  • limit (integer, 非必需): 每内部轮次的批量大小（控制每次轮询显示的属性数量）。
  • offset (integer, 非必需): 分页偏移量。
  • currency (string, 非必需): 报价的ISO货币，例如USD。
• 成功响应 — 顶层字段:
  • success (boolean): 网关成功标志。
  • totalHotels (integer): 聚合后data中的属性数量。
  • limit / offset (integer): 用于查询的分页参数的回显。
  • data[] (array): 每个属性一个对象，包含合并的住宿/交易/媒体字段。
• 每个住宿 (data[] 项) — 在产品中的使用:
  • name, type: 卡片标题和副标题（当存在时，酒店与其他住宿类型）。
  • imageUrl: 主缩略图；在长列表中延迟加载。
  • rating, reviews: 信任徽章，按质量排序/过滤。
  • latitude, longitude: 地图标记，如果您还有中心点，则显示“距中心距离”。
  • pricePerNight, formattedPrice: 主要价格标注；**formattedPrice**对于区域设置一致的显示最安全。
  • advertiser: 突出显示优惠的“在Expedia / 酒店网站 / …上看到”风格归属。
  • dealDescription: 价格下的简短促销行。
  • tags: 用于政策或价值主张的标签（取消政策、餐食等——确切字符串可能不同）。
  • distanceToDestination: 当存在时，“距市中心/搜索中心X公里”风格的文案。
  • clickoutUrl: 交接URL以在合作伙伴处继续；在新标签页或应用内浏览器中打开；除非您了解合作伙伴政策，否则不要嵌入iframe。

推荐集成流程

1. 捕获意图: 用户输入地点；使用去抖动的query调用**search-area**。
2. 解析目的地: 用户选择一行；为会话持久化**id** + ns。
3. 捕获住宿参数: 日期、成人、儿童、首选货币。
4. 加载库存切片: 调用**search；如果需要，显示几秒钟**的加载状态。
5. 交接预订: 在“预订”/“查看优惠”时，在受控的Web上下文中打开**clickoutUrl**；如果允许，为您自己的分析记录出站点击。

操作与UX指南

• 超时: 为search使用宽松的HTTP超时（例如30-60秒，取决于您的技术栈）；保持search-area更严格。
• 缓存: 按规范化查询字符串缓存**search-area结果几分钟；如果可接受过时价格，按完整参数集缓存search结果，使用短TTL**。
• 去重: 避免使用相同请求体触发重复的并发search调用；在客户端中合并进行中的请求。
• 错误: 出现500错误时，提供带退避的重试；仅在开发版本中显示**error**文本，在生产中使用通用文案。
• 可访问性: 为价格和评分提供文本替代方案，而不是仅图像的卡片。

错误处理

• 200: 成功；正文符合记录的成功模式。
• 400: 无效JSON或绑定错误；正文是带有**error**字符串的JSON。
• 500: 服务器或上游故障（超时、拒绝请求、解析错误等）；正文是带有**error**字符串的JSON。

速率限制与合理使用

遵守您的RapidAPI计划中的配额。search比search-area重得多；优先缓存建议，避免并行重复搜索，不要积极抓取。对于生产应用，在错误率和p95延迟上添加客户端速率限制和监控。

术语表

• Metasearch-style: 搜索和比较来自多个来源的优惠；预订通常在其他地方完成。
• Destinationid + ns: 此技术栈中地理或POI概念的复合键——两者都是精确search所必需的。
• Click-out: 用户通过**clickoutUrl**离开您的应用程序，以在合作伙伴网站上完成购买或查看完整条款。
• Polling / aggregation: 服务器端重复获取，直到图谱报告完成（在限制内），然后给您一个JSON响应。

集成者注意事项

• 延迟: 假设多秒的search时间；相应设计UX。
• 模式演进: 可能出现未知的JSON字段；进行防御性解析。
• 合规性: 当显示价格和深层链接时，您负责披露、联盟规则、隐私政策和区域旅行法规。
• 本文档中无上游地址: 网关的操作URL仅适用于RapidAPI / 您的部署；本概述不发布后端基础设施端点。