技術實踐：

導語：在開發旅游或酒店預訂相關的應用程序時，集成第三方平臺的酒店數據是常見需求。攜程作為國內領先的在線旅游服務平臺，提供了豐富的API接口供開發者使用。本文將聚焦于如何使用攜程提供的API接口，通過關鍵詞（如酒店名、地址、地標等）來獲取酒店列表數據。

一、 接口概述

接口功能：本接口主要用于根據用戶輸入的關鍵詞（例如：“北京王府井”、“外灘”、“希爾頓”等）查詢符合條件的酒店列表。

請求方式：通常為GET或POST(具體需參考攜程API文檔)。

認證方式：需要使用攜程分配的唯一密鑰（如App Key和App Secret）進行簽名認證，以確保請求的合法性和安全性。簽名算法一般為HMAC-SHA256或類似。

基礎URL：請求需要發送到攜程API的特定端點，例如：https://api.ctrip.com/hotel/search/v1/list(此為示例，實際URL需以官方文檔為準)。

二、 關鍵請求參數解析

要實現關鍵詞搜索，以下參數至關重要：

keyword(關鍵詞)：

類型：字符串 (String)

說明：用戶輸入的搜索關鍵詞。可以是酒店名稱、地址、商圈、地標、行政區等。

示例：keyword=北京故宮或keyword=上海浦東機場

city(城市)：

類型：字符串 (String) 或 代碼 (Code)

說明：限定搜索的目標城市。通常使用城市的三字碼（如：BJS代表北京，SHA代表上海）或城市中文名。攜帶城市參數能顯著提高搜索的準確性和效率。

示例：city=BJS或city=北京

checkin(入住日期) 和checkout(離店日期)：

類型：字符串 (String)，格式通常為YYYY-MM-DD

說明：指定搜索酒店的可入住日期范圍。這兩個參數通常是必需的。

示例：checkin=2023-10-01&checkout=2023-10-03

page(頁碼) 和pageSize(每頁條數)：

類型：整數 (Int)

說明：用于分頁獲取結果。page指定當前請求的頁碼，pageSize指定每頁返回的酒店數量。

示例：page=1&pageSize=20(獲取第一頁，每頁20條)

sort(排序方式)：

類型：字符串 (String) 或 代碼 (Code)

說明：指定返回結果的排序規則，如按價格、評分、距離等排序。具體可選值需參考文檔。

示例：sort=price_asc(按價格從低到高)

其他可選參數：可能還包括價格范圍 (minPrice,maxPrice)、星級 (star)、品牌 (brand)、設施 (facilities) 等用于進一步篩選結果的參數。

三、 簽名生成 (示例思路)

請求通常需要包含簽名 (sign) 和時間戳 (timestamp) 等認證信息。一個簡化的簽名生成邏輯如下（偽代碼，具體算法以攜程文檔為準）：

import hashlib import hmac import time def generate_sign(app_key, app_secret, params): # 1. 獲取當前時間戳 (秒級) timestamp = str(int(time.time())) # 2. 將除 sign 外的所有請求參數按參數名排序并拼接成字符串 sorted_params = sorted(params.items()) param_str = '&'.join([f"{key}{value}" for key, value in sorted_params]) # 注意: 實際拼接規則可能不同 # 3. 將 app_key, timestamp, param_str 等按特定規則拼接 string_to_sign = f"{app_key}{timestamp}{param_str}" # 4. 使用 app_secret 作為密鑰，對 string_to_sign 進行 HMAC-SHA256 哈希 sign = hmac.new(app_secret.encode('utf-8'), string_to_sign.encode('utf-8'), hashlib.sha256).hexdigest() # 5. 將計算得到的 sign 和 timestamp 加入最終請求參數 params['sign'] = sign params['timestamp'] = timestamp return params

四、 接口響應與解析

請求成功后，接口會返回一個JSON格式的響應體。其核心結構通常包含：

{ "code": 0, // 響應狀態碼 (0 表示成功) "message": "Success", // 響應消息 "data": { "total": 150, // 符合條件的酒店總數 "hotels": [ // 酒店列表數組 { "hotelId": "123456", // 酒店唯一ID "hotelName": "北京王府井希爾頓酒店", // 酒店名稱 "address": "北京市東城區王府井大街1號", // 酒店地址 "star": 5, // 星級 "score": 4.7, // 評分 "price": 800, // 最低價格 (需注意價格單位、幣種、是否含稅等) "image": "https://.../hotel.jpg", // 酒店圖片URL "facilities": ["免費WiFi", "停車場", "游泳池"], // 設施 "location": { // 地理位置信息 (可選) "latitude": 39.9087, "longitude": 116.3974 }, ... // 其他字段如房型、政策等 }, ... // 更多酒店信息 ], "page": 1, // 當前頁碼 "pageSize": 20, // 每頁條數 "totalPage": 8 // 總頁數 } }

開發者需要關注code判斷請求是否成功，解析data.hotels數組來獲取酒店列表信息，并根據total和totalPage實現分頁邏輯。

五、 錯誤處理

仔細檢查code字段。非0通常表示錯誤（如400參數錯誤，401認證失敗，500服務器錯誤等）。

根據message字段提供的錯誤信息進行排查。

常見問題包括：參數缺失或格式錯誤、簽名計算不正確、密鑰無效、請求頻率超限等。

六、 注意事項

查閱官方文檔：以上內容基于常見API設計模式，務必以攜程最新、最全的官方API文檔為準。接口地址、參數名、必選性、響應結構、簽名算法、錯誤碼等細節都可能不同。

API權限申請：使用攜程API需要先在攜程開放平臺注冊開發者賬號并申請相應API的權限，獲取App Key和App Secret。

頻率限制：注意接口的調用頻率限制，避免因頻繁請求導致接口被限流或禁用。

數據緩存：對于非實時性要求極高的場景，考慮合理緩存數據以減少API調用次數。

HTTPS：所有請求均應通過HTTPS協議發送以保證安全。

價格與房態：注意返回的價格信息是否包含稅費、服務費，以及房型的實時庫存狀態（status），這些信息可能需要在后續步驟（如預訂）中進一步確認。

總結：通過攜程的酒店搜索API，開發者可以便捷地在其應用中集成強大的酒店搜索功能。核心在于正確構造包含關鍵詞 (keyword) 和城市 (city) 等關鍵參數的請求，并按照要求進行簽名認證。成功獲取響應后，解析JSON數據即可展示酒店列表。遵循官方文檔、妥善處理認證和錯誤是成功集成的關鍵。

審核編輯 黃宇