マイル検索 API

目的地検索

所持マイルと出発空港から、行ける目的地を検索する。

リクエスト

GET /api/v1/search/destinations

パラメータ	型	必須	説明
origin	string	✅	出発空港コード (e.g., HND)
miles	number	✅	所持マイル数
airline	string		航空会社フィルタ (ANA, JAL, both) デフォルト: both
checkIn	string		チェックイン日 (YYYY-MM-DD)
checkOut	string		チェックアウト日 (YYYY-MM-DD)
guests	number		宿泊人数 デフォルト: 1
seatClass	string		座席クラス デフォルト: economy
sort	string		ソート (miles_asc, miles_desc, cost_asc, score_desc) デフォルト: miles_asc
limit	number		取得件数 デフォルト: 20
offset	number		オフセット デフォルト: 0

レスポンス

{
  "success": true,
  "data": {
    "total": 15,
    "destinations": [
      {
        "airport": {
          "code": "FUK",
          "name": "福岡空港",
          "city": "福岡",
          "prefecture": "福岡県",
          "latitude": 33.585,
          "longitude": 130.451
        },
        "flights": [
          {
            "airline": "ANA",
            "milesRequired": 7500,
            "season": "L",
            "seatClass": "economy",
            "isRoundTrip": false
          },
          {
            "airline": "JAL",
            "milesRequired": 7500,
            "season": "通常",
            "seatClass": "普通席",
            "isRoundTrip": false
          }
        ],
        "bestFlight": {
          "airline": "JAL",
          "milesRequired": 5000,
          "season": "ディスカウント"
        },
        "accommodation": {
          "cheapest": {
            "provider": "agoda",
            "hotelName": "ホテルXYZ",
            "pricePerNight": 3600,
            "rating": 4.1
          },
          "averagePrice": 5200
        },
        "score": {
          "mileValue": 2.1,
          "totalScore": 0.85
        }
      }
    ]
  }
}

レコメンド検索

お得度でランキングした旅行先を返す。

リクエスト

GET /api/v1/search/recommend

パラメータ	型	必須	説明
origin	string	✅	出発空港コード
miles	number	✅	所持マイル数
airline	string		航空会社 デフォルト: both
budget	number		宿泊予算上限(円)
nights	number		宿泊数 デフォルト: 1
guests	number		宿泊人数 デフォルト: 1
weightMile	number		マイル効率の重み (0-1) デフォルト: 0.6
weightAccom	number		宿泊コスパの重み (0-1) デフォルト: 0.4
limit	number		取得件数 デフォルト: 10

レスポンス

{
  "success": true,
  "data": {
    "recommendations": [
      {
        "rank": 1,
        "destination": {
          "code": "FUK",
          "name": "福岡空港",
          "city": "福岡"
        },
        "bestFlight": {
          "airline": "ANA",
          "milesRequired": 7500,
          "normalAirfare": 15800
        },
        "bestAccommodation": {
          "provider": "rakuten",
          "hotelName": "博多エクセルホテル",
          "pricePerNight": 3900,
          "totalPrice": 7800,
          "rating": 4.2
        },
        "scoring": {
          "mileValue": 2.11,
          "accommodationValue": 928,
          "totalScore": 0.89
        },
        "totalCost": {
          "miles": 15000,
          "cash": 7800,
          "milesLabel": "ANA 7,500M × 往復"
        }
      }
    ]
  }
}

シーズン別マップ

特定路線のシーズン別必要マイル数を返す。

リクエスト

GET /api/v1/search/season-map

パラメータ	型	必須	説明
origin	string	✅	出発空港コード
destination	string	✅	到着空港コード
airline	string		航空会社 デフォルト: both
year	number		年 デフォルト: 現在の年

レスポンス

{
  "success": true,
  "data": {
    "route": {
      "origin": "HND",
      "destination": "OKA"
    },
    "months": [
      {
        "month": 1,
        "ana": { "season": "L", "miles": 7000 },
        "jal": { "season": "ディスカウント", "miles": 6000 },
        "avgAccommodation": 4500
      },
      {
        "month": 8,
        "ana": { "season": "H", "miles": 10500 },
        "jal": { "season": "通常", "miles": 9000 },
        "avgAccommodation": 12000
      }
    ]
  }
}