API Content

說明

P0 首頁「全球郵輪」搜尋框的選項：出發地、目的地的選項與預設值，以及出發日期的可選範圍。純艙房與套裝遊在同一個回應，Web 與 App 共用。

• 方法：GET（無參數）

• 快取：不快取，每次呼叫都回當天最新的選項與日期

• 路徑：Cruise/Search/InitSearch

• 對應畫面：P0 首頁「全球郵輪」搜尋框（純艙房／套裝遊）

使用重點：依搜尋框單選取用——純艙房用 Cruise_Info，套裝遊用 Tour_Info；兩者欄位相同：Departure_List（出發地）、Region_List（目的地，一筆＝一個分頁）、DepartureDate_Range（日期）。

純艙房（Cruise_Info）

• ① 出發地：Departure_List，下拉顯示 Display_Text、精簡處顯示 Text；Value 為英文代碼

• ② 目的地：Region_List 兩筆＝兩個分頁，依 Region_Type 區分——Ship（主題遊輪：Regions 一筆＝一個品牌，船在 Ship_List，皆帶英文名 English_Text）、Route（航線，🟡 待定義）；分頁標題 Region_Title，選項顯示 Text

• ③ 理想出發區間：DepartureDate_Range，起日可選 MinDate～MaxDate，迄日自動＝起日＋1 年；預設 Start_Date～End_Date

• 預設：Is_Default＝true 者（每組必有一個；目的地各分頁合計一個）

• 按搜尋：POST Cruise/Search/QueryCruise

套裝遊（Tour_Info）

• ① 出發地：Departure_List，顯示 Text

• ② 目的地：Region_List 一筆（Region_Type＝Area，標題「全球郵輪」），選項 Regions（顯示 Text）

• ③ 出發日期：DepartureDate_Range

• 產品類型：ProductType_List（目前只有「不限」）

• 搜尋參數、搜尋 API：比照原本團體 Web、App API

文件版本：v2.0（未交付）；前端手上是 v1.0（2026/09/24 交付）

規格調整

Request Schema

查詢參數

無參數。

JSON 範例

GET Cruise/Search/InitSearch

Response Schema

回應主體

Result_Info

Result_Data

Cruise_Info

Departure_List（純艙房）

Region_List（純艙房）

Regions（純艙房）

主題遊輪（Ship）的 Regions 一筆＝一個品牌，品牌只是分組標題、不可選，可選的是 Ship_List 裡的船。航線（Route）的 Regions 🟡 內容待定義，目前為空陣列；為空時可只顯示主題遊輪。

Ship_List（純艙房）

DepartureDate_Range（純艙房）

起日可選 MinDate～MaxDate；點選起日後，迄日自動帶入起日＋1 年，不受 MaxDate 限制。預設區間為 Start_Date～End_Date。

Tour_Info

資料同團體行程 SearchInit「國外」的郵輪部分。按搜尋時的搜尋參數與搜尋 API 比照原本團體 Web、App API。團體系統查不到（逾時、錯誤）時整個 Tour_Info 給 null，仍算成功（Is_Success＝true）、純艙房照常；這時選套裝遊顯示「暫時無法查詢」（🟡 文字待 UIUX）。

Departure_List（套裝遊）

Region_List（套裝遊）

Regions（套裝遊）

ProductType_List

DepartureDate_Range（套裝遊）

JSON 範例

{
  "Result_Info": {
    "Is_Success": true,
    "Result_Code": "",
    "Result_Message": ""
  },
  "Result_Data": {
    "Cruise_Info": {
      "Departure_List": [
        {
          "Value": "FlyCruise",
          "Text": "海外登船",
          "Display_Text": "海外登船（不含機票）",
          "Is_Default": true
        },
        {
          "Value": "TWKEL",
          "Text": "基隆港",
          "Display_Text": "基隆港",
          "Is_Default": false
        }
      ],
      "Region_List": [
        {
          "Region_Type": "Ship",
          "Region_Title": "主題遊輪",
          "Regions": [
            {
              "Value": "DCL",
              "Text": "迪士尼郵輪",
              "English_Text": "Disney Cruise Line",
              "Ship_List": [
                {
                  "Value": "DCL-DA",
                  "Text": "迪士尼探險號",
                  "English_Text": "Disney Adventure",
                  "Is_Default": true
                },
                {
                  "Value": "DCL-DW",
                  "Text": "迪士尼奇妙號",
                  "English_Text": "Disney Wonder",
                  "Is_Default": false
                }
              ]
            }
          ]
        },
        {
          "Region_Type": "Route",
          "Region_Title": "航線",
          "Regions": []
        }
      ],
      "DepartureDate_Range": {
        "Start_Date": "2026/11/09",
        "End_Date": "2027/11/09",
        "MinDate": "2026/11/09",
        "MaxDate": "2027/11/09"
      }
    },
    "Tour_Info": {
      "Departure_List": [
        {
          "Value": "*",
          "Text": "不限"
        },
        {
          "Value": "基隆",
          "Text": "基隆"
        },
        {
          "Value": "台北",
          "Text": "台北（不限機場）"
        },
        {
          "Value": "松山",
          "Text": "台北（松山機場）"
        },
        {
          "Value": "桃園",
          "Text": "台北（桃園機場）"
        },
        {
          "Value": "台中",
          "Text": "台中"
        },
        {
          "Value": "高雄",
          "Text": "高雄"
        },
        {
          "Value": "花蓮",
          "Text": "花蓮"
        }
      ],
      "Region_List": [
        {
          "Region_Type": "Area",
          "Region_Title": "全球郵輪",
          "Regions": [
            {
              "Value": "N",
              "Text": "全球郵輪"
            },
            {
              "Value": "N-01",
              "Text": "亞洲郵輪（基隆港往返、日韓、東南亞、中港澳）"
            },
            {
              "Value": "N-02",
              "Text": "美洲郵輪（阿拉斯加、美墨、美加東、夏威夷、加勒比海）"
            },
            {
              "Value": "N-03",
              "Text": "歐洲郵輪（地中海、英國北歐、波羅的海）"
            },
            {
              "Value": "N-04",
              "Text": "歐洲河輪（塞納河、斗羅河、多瑙河、隆河、萊茵河）"
            },
            {
              "Value": "N-07",
              "Text": "中東郵輪（波斯灣、阿拉伯海）"
            },
            {
              "Value": "N-06",
              "Text": "台灣出發郵輪（基隆港／高雄港往返）"
            }
          ]
        }
      ],
      "ProductType_List": [
        {
          "Value": "全部",
          "Text": "不限"
        }
      ],
      "DepartureDate_Range": {
        "Start_Date": "2026/10/01",
        "End_Date": "2028/09/30",
        "MinDate": "2026/10/01",
        "MaxDate": "2028/09/30"
      }
    }
  }
}

範例值為示意，實際選項與日期以回傳為準。

錯誤回應

200 的代碼在 Result_Info.Result_Code、訊息在 Result_Message；400、500 只回一句訊息，代碼在訊息開頭（格式「代碼｜訊息」，例「4002｜Start_Date 格式錯誤」）。訊息欄除了「重複訂位」與「出發日期已無法訂購，請重新選擇」已定，其他是暫定文字，UIUX 定稿後只改文字、不改代碼；N＝第幾間。

測試情境/單元測試(開發前規劃)

畫面呼叫

舊版畫面

新版畫面

P0 首頁「全球郵輪」搜尋框：進頁呼叫本 API → 依單選（純艙房／套裝遊）取 Cruise_Info 或 Tour_Info → 出發地／目的地選單與出發日期月曆 → 按搜尋（純艙房呼叫 POST Cruise/Search/QueryCruise 進 P1）。雛形：UIUX 20260922 版 P0 SearchBar 元件（① 出發地、② 目的地、② 套裝遊／目的地、③ 理想出發區間，含「任點選一個日期，自動帶入一年後的日期」操作）。

畫面欄位對照（WEB）

先看純艙房搜尋框（雛形 WEB P0-W01）；灰色虛線＝不在本 API。目的地、理想出發區間、套裝遊另拉細節圖。圖片可點開放大。

細節 1：目的地（P0-W02）

細節 2：理想出發區間（P0-W04）

細節 3：套裝遊（P0-W03）

P0 不用：Departure_List 的 Text（短名，P1 頁首等精簡處才用）。雛形還沒畫、圖上沒標：目的地下拉的品牌分組標題與英文名（Regions 的 Text、English_Text，Ship_List 的 English_Text）；套裝遊的產品類型（ProductType_List）。各截圖右邊的手機寬度版欄位相同，不另標。

畫面欄位對照（APP）

先看純艙房頁籤（雛形 APP P0-A01）；目的地面板、頁籤版型另拉細節圖。圖片可點開放大。

細節 1：目的地面板（P0-A02 左；現在只有主題郵輪，頁籤隱藏）

細節 2：目的地頁籤版型（P0-A02 右；航線上線後）

P0 不用：Departure_List 的 Text（同 WEB）。雛形還沒畫、圖上沒標：選理想出發區間的畫面（MinDate 之前反灰、MaxDate）；「套裝遊」頁籤整頁（Tour_Info 全部欄位）。