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