amadeus-hotels

# Amadeus Hotels Skill 🏨 Search hotel prices, availability, and ratings via the Amadeus Self-Service API. Perfect for vacation planning and deal hunting. ## Setup 1. **Get API credentials** at https://developers.amadeus.com/self-service - Create account → My Apps → Create new app - Copy API Key and API Secret 2. **Set environment variables:** ```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. **Install dependency:** ```bash pip install requests ``` **Free tier:** ~2,000 requests/month in test, pay-per-use after in production. ## Quick Reference | Task | Script | Example | |------|--------|---------| | Search by city | `scripts/search.py` | `--city PAR --checkin 2026-03-15 --checkout 2026-03-20` | | Get offers | `scripts/offers.py` | `--hotels HTPAR123,HTPAR456 --adults 2` | | Offer details | `scripts/details.py` | `--offer-id ABC123` | | Track price | `scripts/track.py` | `--add --hotel HTPAR123 --target 150` | | Check tracked | `scripts/track.py` | `--check` | ## Capabilities ### 1. Hotel Search Find hotels by city code (IATA) or coordinates: ```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 ``` **Common city codes:** PAR (Paris), NYC (New York), TYO (Tokyo), BCN (Barcelona), LON (London), LAX (Los Angeles), SFO (San Francisco) ### 2. Get Pricing & Availability Once you have hotel IDs from search: ```bash python3 <skill>/scripts/offers.py \ --hotels HTPAR001,HTPAR002 \ --checkin 2026-03-15 \ --checkout 2026-03-20 \ --adults 2 \ --rooms 1 ``` Returns: Room types, prices, cancellation policies, board types. ### 3. Offer Details Get full details for a specific offer before booking: ```bash python3 <skill>/scripts/details.py --offer-id <offer-id-from-search> ``` Returns: Detailed room info, full cancellation policy, payment terms, hotel contact. ### 4. Hotel Ratings & Sentiment Get aggregated review sentiment: ```bash python3 <skill>/scripts/details.py --hotel-id HTPAR001 --ratings ``` Returns: Overall score (0-100), category scores (Staff, Location, WiFi, Cleanliness, etc.) ### 5. Price Tracking Track hotels and get alerts when prices drop: ```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 Setup for Price Alerts Add to OpenClaw cron for automatic price monitoring: ```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" ``` When prices drop below target, the script outputs alert text. Configure your notification channel in the cron task. ## Output Formatting Scripts output JSON by default. Add `--format human` for readable output: ```bash python3 <skill>/scripts/search.py --city PAR --format human ``` Human format example: ``` 🏨 Hotel & Spa Paris Marais ★★★★ 📍 15 Rue du Temple, Paris 💰 €189/night (was €220) ✨ WIFI, SPA, RESTAURANT 📊 Rating: 87/100 (Staff: 92, Location: 95) ``` ## Amenity Codes Common filters for `--amenities`: | Code | Meaning | |------|---------| | WIFI | Free WiFi | | POOL | Swimming pool | | SPA | Spa/wellness | | GYM | Fitness center | | RESTAURANT | On-site restaurant | | PARKING | Parking available | | PETS_ALLOWED | Pet-friendly | | AIR_CONDITIONING | A/C | | KITCHEN | Kitchen/kitchenette | Full list in `references/amenities.md`. ## ⚠️ Important: Pricing Disclaimer **Amadeus API prices are NOT retail prices.** The API returns negotiated, net, or wholesale rates — not the public prices you see on Booking.com, Expedia, or hotel websites. Key differences: - **Net vs Retail:** API returns "net rates" (raw cost), not marked-up retail prices - **B2B Pricing:** Designed for travel agencies/developers to add their own markup - **Negotiated Rates:** May include corporate or consortia rates unavailable to consumers - **Tax Breakdown:** Prices often show base + taxes separately **Use these prices for comparison and tracking trends**, not as exact retail quotes. Actual booking prices on consumer sites will differ. ## Limitations & Notes - **Test environment:** Limited/cached data, not real-time. Good for development. - **Production:** Real prices but requires "Move to Production" in Amadeus dashboard. - **No direct booking:** API returns offer details; actual booking requires payment handling (PCI compliance). - **Rate limits:** 10 TPS (test), 40 TPS (production). Scripts include backoff. - **Data freshness:** Prices change frequently. Always re-check before booking elsewhere. - **Not retail prices:** See pricing disclaimer above. ## Error Handling | Error | Meaning | Action | |-------|---------|--------| | 401 | Auth failed | Check API key/secret | | 429 | Rate limited | Wait and retry (auto-handled) | | 400 | Bad request | Check parameters (dates, codes) | | No results | No availability | Try different dates or expand search | ## References - `references/amenities.md` — Full amenity code list - https://developers.amadeus.com/self-service/apis-docs — Official API docs