amadeus-hotels

name	amadeus-hotels
description	Search hotel prices and availability via Amadeus API. Find vacation hotels by city, coordinates, or amenities. Compare prices, view ratings, get offer details. Track prices with alerts. Use when user asks to "find hotels", "search hotels in [city]", "hotel prices", "vacation accommodation", "hotel deals", "track hotel price".
homepage	https://github.com/kesslerio/amadeus-hotels-clawhub-skill
metadata	{"openclaw":{"emoji":"🏨","requires":{"bins":["python3"],"env":["AMADEUS_API_KEY","AMADEUS_API_SECRET"]},"primaryEnv":"AMADEUS_API_KEY","install":[{"id":"pip-requests","kind":"pip","packages":["requests"],"label":"Install requests (pip)"}]}}

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:

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:

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:

# 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:

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:

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:

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:

# 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:

# 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:

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