Skill: yangms30/hotel-price-finder (version 1.1.0)

--- name: hotel-price-finder version: 1.1.0 description: Compare hotel prices across Booking.com, Agoda, Trip.com in real-time. Free multi-OTA price comparison with direct booking links. No API key required. tags: [travel, hotel, agoda, booking, price-comparison, trip, expedia, cheapest, deal] env: - APIFY_API_KEY (optional - Agoda deep search with 22+ fields) --- # Hotel Price Finder - Multi OTA Compare real-time hotel prices across Booking.com, Agoda, Trip.com and more. No API key required. ## When to Use Activate when user asks about hotel search, price comparison, cheapest booking site, or accommodation recommendations. ## Step 1: Parse Query Extract: `destination` (required), `checkIn`/`checkOut` (required, YYYY-MM-DD), `adults` (default 2), `rooms` (default 1), `currency` (default USD), `maxBudget`, `limit` (default 10). If dates missing, ask the user. ## Step 2: Resolve Destination ### Xotelo Location Key Xotelo uses TripAdvisor keys (`g{number}`). For unlisted cities, call: ```bash curl -s "https://data.xotelo.com/api/search?q=DESTINATION&limit=5" ``` Common keys: Seoul=g294197, Busan=g297884, Jeju=g983296, Tokyo=g298184, Osaka=g298566, Kyoto=g298564, Bangkok=g293916, Phuket=g293920, Singapore=g294265, Bali=g294226, Kuala Lumpur=g298570, Hong Kong=g294217, Taipei=g293913, Da Nang=g298085, Ho Chi Minh=g293925, Hanoi=g293924, Cebu=g294261, Manila=g298573, Paris=g187147, London=g186338, New York=g60763 ### Agoda City ID (for booking links) ```bash curl -s "https://www.agoda.com/api/cronos/search/GetUnifiedSuggestResult/3/1/1/0/en-us/?searchText=DESTINATION&origin=US" \ -H "User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36" ``` Extract `ObjectId` where `PageTypeId == 5` and `SearchType == 1`. Common IDs: Seoul=14690, Busan=17172, Tokyo=5085, Osaka=9590, Bangkok=9395, Singapore=4064, Bali=17193, Hong Kong=16808 ## Step 3: Search Hotels (Xotelo API - Free) ### Get Hotel List ```bash curl -s "https://data.xotelo.com/api/list?location_key=${LOCATION_KEY}&limit=${LIMIT}" ``` Returns per hotel: `name`, `key`, `review_summary.rating` (out of 5), `review_summary.count`, `price_ranges.minimum/maximum`, `geo`, `image`, `url`. ### Get OTA Prices ```bash curl -s "https://data.xotelo.com/api/rates?hotel_key=${HOTEL_KEY}&chk_in=${CHECK_IN}&chk_out=${CHECK_OUT}&currency=${CURRENCY}" ``` Returns per OTA: `code`, `name`, `rate` (before tax), `tax`. Add 1s delay between requests. ### Generate Booking Links Xotelo doesn't provide booking URLs. Build them per OTA (URL-encode hotel name as `{H}`): | OTA Code | Booking URL | |----------|-------------| | BookingCom | `https://www.booking.com/searchresults.html?ss={H}&checkin={CHECK_IN}&checkout={CHECK_OUT}&group_adults={ADULTS}&no_rooms={ROOMS}` | | Agoda | `https://www.agoda.com/search?q={H}&city={AGODA_CITY_ID}&checkIn={CHECK_IN}&checkOut={CHECK_OUT}&los={LOS}&rooms={ROOMS}&adults={ADULTS}` | | CtripTA | `https://www.trip.com/hotels/list?keyword={H}&checkin={CHECK_IN}&checkout={CHECK_OUT}` | | HotelsCom | `https://www.hotels.com/search.do?q={H}&checkin={CHECK_IN}&checkout={CHECK_OUT}` | | Expedia | `https://www.expedia.com/Hotel-Search?destination={H}&d1={CHECK_IN}&d2={CHECK_OUT}&adults={ADULTS}&rooms={ROOMS}` | ### Price Heatmap (optional, for flexible dates) ```bash curl -s "https://data.xotelo.com/api/heatmap?hotel_key=${HOTEL_KEY}&currency=${CURRENCY}" ``` ## Step 4: Apify Mode (Optional) If `APIFY_API_KEY` is set, use for Agoda-specific deep search: ```bash curl -s -X POST "https://api.apify.com/v2/acts/knagymate~fast-agoda-scraper/runs?[REDACTED_SECRET]" \ -H "Content-Type: application/json" \ -d '{"city":"'"${DESTINATION}"'","checkIn":"'"${CHECK_IN}"'","checkOut":"'"${CHECK_OUT}"'","rooms":'"${ROOMS}"',"adults":'"${ADULTS}"',"currency":"'"${CURRENCY}"'","maxItems":15}' ``` Poll `.data.status` until SUCCEEDED, then fetch from `.data.defaultDatasetId`. ## Step 5: Output Format ``` ## 🏨 Hotel Search: [Destination] 📅 [CheckIn] → [CheckOut] ([N] nights) | 👤 [Adults] | 🛏️ [Rooms] room(s) ### #1 [Hotel Name] ⭐ [Rating]/5 ([Reviews] reviews) | OTA | Rate | Tax | Total | Book | |-----|------|-----|-------|------| | **Agoda** | $280 | $53 | **$333 ← Best** | [Book](url) | | Trip.com | $347 | $34 | $381 | [Book](url) | 💡 Save $82 by booking on Agoda vs Booking.com! ``` Rules: Sort OTAs cheapest first. Mark best deal. Show savings. Always include booking links. Include Agoda full search URL at bottom. ## Error Handling - Destination not found → try Xotelo search API, then ask user - `chk_in is invalid` → dates may be too far out, try within 1 year - No OTA rates → show TripAdvisor link instead - Apify fail → auto fallback to Xotelo free mode - Rate limit → add 1s delay, limit to 5 hotels per batch

path: examples/sample-output.json
content: {
  "meta": {
    "destination": "Seoul",
    "locationKey": "g294197",
    "agodaCityId": 14690,
    "checkIn": "2026-04-10",
    "checkOut": "2026-04-12",
    "nights": 2,
    "adults": 2,
    "rooms": 1,
    "currency": "USD",
    "mode": "free_xotelo",
    "agodaSearchUrl": "https://www.agoda.com/search?city=14690&checkIn=2026-04-10&checkOut=2026-04-12&los=2&rooms=1&adults=2&currency=USD",
    "totalHotelsInCity": 4170
  },
  "hotels": [
    {
      "rank": 1,
      "name": "Hotel the BOTANIK Sewoon Myeongdong",
      "key": "g294197-d32743802",
      "type": "Hotel",
      "rating": 4.9,
      "reviewCount": 352,
      "priceRange": { "min": 113, "max": 301 },
      "geo": { "lat": 37.56747, "lng": 126.99403 },
      "otaPrices": [
        {
          "ota": "Agoda.com",
          "code": "Agoda",
          "rate": 280,
          "tax": 53,
          "total": 333,
          "bookingUrl": "https://www.agoda.com/search?q=Hotel%20the%20BOTANIK%20Sewoon%20Myeongdong&city=14690&checkIn=2026-04-10&checkOut=2026-04-12&los=2&rooms=1&adults=2"
        },
        {
          "ota": "Trip.com",
          "code": "CtripTA",
          "rate": 347,
          "tax": 34,
          "total": 381,
          "bookingUrl": "https://www.trip.com/hotels/list?keyword=Hotel%20the%20BOTANIK%20Sewoon%20Myeongdong&checkin=2026-04-10&checkout=2026-04-12"
        },
        {
          "ota": "Vio.com",
          "code": "Vio",
          "rate": 371,
          "tax": 37,
          "total": 408,
          "bookingUrl": "https://www.vio.com/?q=Hotel%20the%20BOTANIK%20Sewoon%20Myeongdong"
        },
        {
          "ota": "Booking.com",
          "code": "BookingCom",
          "rate": 348,
          "tax": 67,
          "total": 415,
          "bookingUrl": "https://www.booking.com/searchresults.html?ss=Hotel%20the%20BOTANIK%20Sewoon%20Myeongdong&checkin=2026-04-10&checkout=2026-04-12&group_adults=2&no_rooms=1"
        }
      ],
      "bestDeal": { "ota": "Agoda.com", "total": 333 },
      "savings": 82,
      "savingsNote": "Save $82 by booking on Agoda.com vs Booking.com"
    },
    {
      "rank": 2,
      "name": "Hotel Skypark Myeongdong 3",
      "key": "g294197-d2202400",
      "type": "Hotel",
      "rating": 4.7,
      "reviewCount": 2272,
      "priceRange": { "min": 113, "max": 314 },
      "otaPrices": [
        {
          "ota": "Trip.com",
          "code": "CtripTA",
          "rate": 266,
          "tax": 26,
          "total": 292,
          "bookingUrl": "https://www.trip.com/hotels/list?keyword=Hotel%20Skypark%20Myeongdong%203&checkin=2026-04-10&checkout=2026-04-12"
        },
        {
          "ota": "Agoda.com",
          "code": "Agoda",
          "rate": 253,
          "tax": 50,
          "total": 303,
          "bookingUrl": "https://www.agoda.com/search?q=Hotel%20Skypark%20Myeongdong%203&city=14690&checkIn=2026-04-10&checkOut=2026-04-12&los=2&rooms=1&adults=2"
        },
        {
          "ota": "Booking.com",
          "code": "BookingCom",
          "rate": 276,
          "tax": 58,
          "total": 334,
          "bookingUrl": "https://www.booking.com/searchresults.html?ss=Hotel%20Skypark%20Myeongdong%203&checkin=2026-04-10&checkout=2026-04-12&group_adults=2&no_rooms=1"
        },
        {
          "ota": "Vio.com",
          "code": "Vio",
          "rate": 368,
          "tax": 36,
          "total": 404,
          "bookingUrl": "https://www.vio.com/?q=Hotel%20Skypark%20Myeongdong%203"
        }
      ],
      "bestDeal": { "ota": "Trip.com", "total": 292 },
      "savings": 112,
      "savingsNote": "Save $112 by booking on Trip.com vs Vio.com"
    }
  ]
}


path: README.md
content: # hotel-price-finder

Real-time hotel price comparison across Booking.com, Agoda, Trip.com & more. Find the cheapest OTA for any hotel, instantly. No API key required.

## What It Does

Search any city → Get hotel list with ratings → Compare real-time prices across OTAs → Find the best deal.

```
🏨 Hotel Search: Seoul
📅 Apr 10-12 (2 nights) | 👤 2 adults

1. Hotel Skypark Myeongdong 3 - ⭐ 4.7 (2,272 reviews)
   Trip.com: $292 | Agoda: $303 | Booking.com: $334
   → Trip.com saves you $42 vs Booking.com!
```

## Modes

| Mode | Requirement | What You Get |
|------|------------|--------------|
| **Free** (default) | None | Hotel list + real-time OTA price comparison via Xotelo |
| **Agoda Direct** | None | City lookup + Agoda search URL + area recommendations |
| **Apify** (optional) | `APIFY_API_KEY` | Agoda-specific deep search (22+ fields per hotel) |

## Install

```bash
npx clawhub@latest install hotel-price-finder
```

## Setup

### Free Mode (default)
No setup needed. Works immediately using Xotelo's free API.

### Apify Mode (optional)
```bash
export APIFY_API_KEY="your_apify_api_key_here"
```

## Usage Examples

- "Find hotels in Seoul for May 1-3"
- "Compare hotel prices in Bangkok under $50/night"
- "Which OTA is cheapest for Hotel Skypark Myeongdong?"
- "서울 명동 근처 호텔 5월 1일~3일 2명"
- "Show me the cheapest dates for this hotel" (heatmap)

## Data Sources

### Free Mode (Xotelo API)
- Hotel list: name, rating, review count, price range, GPS, image
- OTA price comparison: Booking.com, Agoda, Trip.com, Vio.com, Hotels.com, Expedia
- Price heatmap: cheapest dates visualization

### Agoda Direct
- City/area lookup via Agoda autocomplete API
- Pre-built search URLs with all filters

### Apify Mode
- 22+ fields: name, star rating, detailed pricing, facilities, photos, policies

## Supported Cities

25+ cities pre-mapped including Seoul, Tokyo, Osaka, Bangkok, Singapore, Bali, Hong Kong, Taipei, Paris, London, New York, and more. Any city searchable via Xotelo search API.

## License

MIT


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)