核心用法
google-hotels-availability 是 StayingAPI 提供的酒店房源可用性查询技能，专为需要精确掌握特定房源日历状态的场景设计。用户可通过 GET /v1/availability 端点，查询单个或批量房源在指定日期窗口内的逐日可用性数据，包括是否可预订、最小入住夜数限制、是否允许入住/退房等关键信息。
该技能采用平台参数化设计，platform 字段支持 google/airbnb/booking/vrbo 四种值，实现一套 API 覆盖主流 OTA 平台。请求需提供 startDate 和 endDate（窗口不超过 365 天），支持通过 listingId 单查或 listingIds[] 批量查询，也可用完整房源 URL 作为替代参数。
针对实时抓取场景，API 采用异步任务模式：首次请求返回 202 状态码及 jobId，需轮询 GET /v1/jobs/{jobId} 直至状态变为 completed 或 failed。轮询需遵守 Retry-After 头部建议，避免触发 429 限流（120 次/分钟）。
显著优点
跨平台统一 Schema 是本技能最大亮点。Google Hotels、Airbnb、Booking.com、Vrbo 四大平台的数据以相同结构返回，大幅降低多平台接入成本。配合 /v1/price-compare 端点，可获取同一房源在多个 OTA 的价格对比及 StayingAPI 计算的最低价/中位数参考。
零成本评估机制 极具吸引力：stay_test_ 前缀的 sandbox key 完全免费，适合开发测试；生产环境采用"成功才计费"模式——失败、空结果、被封禁的请求均不扣费，降低试错成本。
MCP 原生支持 让密钥管理更安全。支持通过 https://mcp.stayingapi.com/mcp 以 OAuth 2.1 + PKCE 协议连接，无需在 Agent 中硬编码 API key。
潜在缺点与局限性
平台能力不均 是明显短板：Google Hotels 虽支持搜索、价格、比价，但缺失房源详情（/v1/listing）和评价（/v1/reviews）端点，需切换至其他平台补齐信息。
异步流程增加复杂度。实时抓取需轮询任务状态，开发者需自行实现退避策略和最大尝试次数限制，否则易触发速率限制。
外部 ID 可靠性问题。非 StayingAPI 搜索渠道获取的 Vrbo 房源 ID 可能解析失败（all_actors_failed），建议优先使用 /v1/search 返回的 platformListingId。
分页行为因端点而异。limit/cursor 参数虽被接受，但实际分页逻辑取决于上游源和端点实现，需以响应中的 meta.pagination 为准。
适合的目标群体
- 旅行规划 Agent：需为用户查询特定房源档期可用性的对话式 AI
- 价格监控工具：追踪多平台房源日历变化的价格情报系统
- 民宿运营工具：管理跨平台房源状态的短租运营 SaaS
- 企业差旅平台：集成酒店查询能力的 B2B 差旅管理系统
使用风险
网络依赖：必须能访问 api.stayingapi.com，无离线能力。
速率限制：生产环境 120 请求/分钟，高频轮询需配合退避策略。
数据时效性：异步任务可能耗时数秒至数十秒，estimatedSeconds 仅为估计值。
平台政策风险：OTA 平台可能调整反爬策略，导致抓取失败率上升。
密钥安全：虽支持 MCP OAuth，但传统 Bearer Token 模式需妥善保管 STAYINGAPI_KEY。