宿泊検索 API

宿泊横断検索

4社の宿泊予約サイトから一括検索し、統一フォーマットで返す。

リクエスト

GET /api/v1/accommodation/search

パラメータ	型	必須	説明
destination	string	✅	目的地（都市名 or 空港コード）
checkIn	string	✅	チェックイン日 (YYYY-MM-DD)
checkOut	string	✅	チェックアウト日 (YYYY-MM-DD)
guests	number		宿泊人数 デフォルト: 1
rooms	number		部屋数 デフォルト: 1
maxPrice	number		1泊上限料金(円)
minRating	number		最低評価 (0-5)
providers	string		カンマ区切りのプロバイダー デフォルト: all
sort	string		ソート (price_asc, price_desc, rating_desc) デフォルト: price_asc
limit	number		取得件数 デフォルト: 20
offset	number		オフセット デフォルト: 0

レスポンス

{
  "success": true,
  "data": {
    "total": 48,
    "searchParams": {
      "destination": "福岡",
      "checkIn": "2024-07-20",
      "checkOut": "2024-07-22",
      "guests": 2,
      "rooms": 1
    },
    "results": [
      {
        "provider": "agoda",
        "hotelId": "agoda-12345",
        "hotelName": "ホテルXYZ福岡",
        "pricePerNight": 3600,
        "totalPrice": 7200,
        "currency": "JPY",
        "rating": 4.1,
        "reviewCount": 892,
        "address": "福岡県福岡市博多区○○1-2-3",
        "latitude": 33.590,
        "longitude": 130.420,
        "imageUrl": "https://...",
        "bookingUrl": "https://...",
        "cancelPolicy": "3日前まで無料キャンセル",
        "fetchedAt": "2024-07-15T10:30:00Z"
      },
      {
        "provider": "rakuten",
        "hotelId": "rakuten-67890",
        "hotelName": "博多エクセルホテル",
        "pricePerNight": 3900,
        "totalPrice": 7800,
        "currency": "JPY",
        "rating": 4.2,
        "reviewCount": 1234,
        "address": "福岡県福岡市博多区△△2-3-4",
        "latitude": 33.592,
        "longitude": 130.418,
        "imageUrl": "https://...",
        "bookingUrl": "https://...",
        "cancelPolicy": "前日まで無料キャンセル",
        "fetchedAt": "2024-07-15T10:30:00Z"
      }
    ],
    "providerStatus": {
      "rakuten": { "status": "ok", "count": 15 },
      "agoda": { "status": "ok", "count": 12 },
      "tripcom": { "status": "ok", "count": 11 },
      "bookingcom": { "status": "ok", "count": 10 }
    }
  }
}

同一ホテル比較

同一ホテルの各サイトでの料金を比較する。

リクエスト

GET /api/v1/accommodation/compare

パラメータ	型	必須	説明
hotelName	string	✅	ホテル名
destination	string	✅	目的地
checkIn	string	✅	チェックイン日
checkOut	string	✅	チェックアウト日
guests	number		宿泊人数 デフォルト: 1

レスポンス

{
  "success": true,
  "data": {
    "hotelName": "博多エクセルホテル",
    "prices": [
      {
        "provider": "bookingcom",
        "pricePerNight": 3800,
        "totalPrice": 7600,
        "bookingUrl": "https://...",
        "cancelPolicy": "前日まで無料"
      },
      {
        "provider": "rakuten",
        "pricePerNight": 3900,
        "totalPrice": 7800,
        "bookingUrl": "https://...",
        "cancelPolicy": "前日まで無料"
      },
      {
        "provider": "agoda",
        "pricePerNight": 4100,
        "totalPrice": 8200,
        "bookingUrl": "https://...",
        "cancelPolicy": "3日前まで無料"
      },
      {
        "provider": "tripcom",
        "pricePerNight": 4200,
        "totalPrice": 8400,
        "bookingUrl": "https://...",
        "cancelPolicy": "当日まで無料"
      }
    ],
    "bestDeal": {
      "provider": "bookingcom",
      "savings": 800,
      "savingsPercent": 9.5
    }
  }
}

プロバイダー別の注意事項

プロバイダー	レート制限	キャッシュ	備考
楽天トラベル	1req/sec	1時間	applicationId 必要
agoda	10req/min	1時間	パートナーキー必要
trip.com	要確認	1時間	アフィリエイトID必要
booking.com	5req/sec	1時間	RapidAPIキー必要