介绍
# Amadeus Hotels Skill 🏨
通过 Amadeus 自助服务 API 搜索酒店价格、可用性和评分。非常适合度假规划和优惠搜寻。
## 设置
1. **获取 API 凭据**，访问 https://developers.amadeus.com/self-service - 创建账户 → My Apps → 创建新应用 - 复制 API Key 和 API Secret
2. **设置环境变量：** ```bash export AMADEUS_API_KEY="your-api-key" export AMADEUS_API_SECRET="your-api-secret" export AMADEUS_ENV="test" # or "production" for real bookings ```
3. **安装依赖：** ```bash pip install requests ```
**免费层级：** 测试环境每月约 2,000 次请求，生产环境按使用量付费。
## 快速参考
| 任务 | 脚本 | 示例 | |------|--------|---------| | 按城市搜索 | `scripts/search.py` | `--city PAR --checkin 2026-03-15 --checkout 2026-03-20` | | 获取优惠 | `scripts/offers.py` | `--hotels HTPAR123,HTPAR456 --adults 2` | | 优惠详情 | `scripts/details.py` | `--offer-id ABC123` | | 价格追踪 | `scripts/track.py` | `--add --hotel HTPAR123 --target 150` | | 检查追踪 | `scripts/track.py` | `--check` |
## 功能
### 1. 酒店搜索
通过城市代码（IATA）或坐标查找酒店：
```bash # By city python3 <skill>/scripts/search.py --city PAR --checkin 2026-03-15 --checkout 2026-03-20
# By coordinates (near a landmark) python3 <skill>/scripts/search.py --lat 48.8584 --lon 2.2945 --radius 5 --checkin 2026-03-15 --checkout 2026-03-20
# With filters python3 <skill>/scripts/search.py --city NYC --amenities WIFI,POOL,SPA --ratings 4,5 ```
**常用城市代码：** PAR (巴黎), NYC (纽约), TYO (东京), BCN (巴塞罗那), LON (伦敦), LAX (洛杉矶), SFO (旧金山)
### 2. 获取价格与可用性
当您从搜索结果中获取酒店 ID 后：
```bash python3 <skill>/scripts/offers.py \ --hotels HTPAR001,HTPAR002 \ --checkin 2026-03-15 \ --checkout 2026-03-20 \ --adults 2 \ --rooms 1 ```
返回：房型、价格、取消政策、餐食类型。
### 3. 优惠详情
在预订前获取特定优惠的完整详情：
```bash python3 <skill>/scripts/details.py --offer-id <offer-id-from-search> ```
返回：详细房间信息、完整取消政策、付款条款、酒店联系方式。
### 4. 酒店评分与情感
获取聚合的评论情感：
```bash python3 <skill>/scripts/details.py --hotel-id HTPAR001 --ratings ```
返回：总体评分（0-100），分类评分（员工、位置、WiFi、清洁度等）。
### 5. 价格追踪
追踪酒店并在价格下降时接收提醒：
```bash # Add hotel to tracking python3 <skill>/scripts/track.py --add \ --hotel HTPAR001 \ --checkin 2026-03-15 \ --checkout 2026-03-20 \ --adults 2 \ --target 150 # Alert if price drops below $150/night
# Check all tracked hotels (run via cron) python3 <skill>/scripts/track.py --check
# List tracked hotels python3 <skill>/scripts/track.py --list
# Remove from tracking python3 <skill>/scripts/track.py --remove --hotel HTPAR001 ```
### 价格提醒的 Cron 设置
添加到 OpenClaw cron 以自动监控价格：
```yaml # Check hotel prices twice daily - schedule: "0 9,18 * * *" task: "Run hotel price tracker and alert on drops" command: "python3 <skill>/scripts/track.py --check" ```
当价格低于目标时，脚本会输出提醒文本。在 cron 任务中配置您的通知渠道。
## 输出格式化
脚本默认输出 JSON。添加 `--format human` 以获取可读输出：
```bash python3 <skill>/scripts/search.py --city PAR --format human ```
人类可读格式示例： ``` 🏨 Hotel & Spa Paris Marais ★★★★ 📍 15 Rue du Temple, Paris 💰 €189/night (was €220) ✨ WIFI, SPA, RESTAURANT 📊 Rating: 87/100 (Staff: 92, Location: 95) ```
## 设施代码
`--amenities` 的常用筛选条件：
| 代码 | 含义 | |------|---------| | WIFI | 免费 WiFi | | POOL | 游泳池 | | SPA | SPA/康体 | | GYM | 健身中心 | | RESTAURANT | 现场餐厅 | | PARKING | 提供停车 | | PETS_ALLOWED | 允许宠物 | | AIR_CONDITIONING | 空调 | | KITCHEN | 厨房/简易厨房 |
完整列表请参见 `references/amenities.md`。
## ⚠️ 重要：价格免责声明
**Amadeus API 价格并非零售价格。** API 返回的是协议价、净价或批发价——而非您在 Booking.com、Expedia 或酒店网站上看到的公开价格。
主要区别： - **净价 vs 零售价：** API 返回“净价”（原始成本），而非加价的零售价格。 - **B2B 定价：** 专为旅行社/开发者设计，以便自行添加加价。 - **协议价：** 可能包含企业或联盟价格，这些价格不对消费者开放。 - **税费明细：** 价格通常分别显示基础价格和税费。
**请将这些价格用于比较和追踪趋势**，不要作为确切的零售报价。消费者网站上的实际预订价格会有所不同。
## 限制与说明
- **测试环境：** 数据有限/缓存数据，非实时。适合开发。 - **生产环境：** 实时价格，但需要在 Amadeus 仪表板中点击“Move to Production”。 - **无直接预订：** API 返回优惠详情；实际预订需要处理支付（PCI 合规）。 - **速率限制：** 10 TPS（测试），40 TPS（生产）。脚本包含退避机制。 - **数据新鲜度：** 价格变化频繁。在其他地方预订前务必重新检查。 - **非零售价格：** 参见上面的价格免责声明。
## 错误处理
| 错误 | 含义 | 操作 | |-------|---------|--------| | 401 | 认证失败 | 检查 API key/secret | | 429 | 速率受限 | 等待并重试（自动处理） | | 400 | 错误请求 | 检查参数（日期、代码）| | 无结果 | 无可用房 | 尝试不同日期或扩大搜索范围 |
## 参考资料
- `references/amenities.md` — 完整设施代码列表 - https://developers.amadeus.com/self-service/apis-docs — 官方 API 文档