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