輸入提示白標旅遊平台 API

在旅客搜尋時提供建議

Typehead (GET /suggestions) 是一個全新的 API 端點，讓您能根據地理區域、相關地點及可用房源，為旅客提供具建議性的搜尋體驗。此端點會根據使用者輸入的局部搜尋字串及任何請求參數，返回建議清單。請聯絡您的帳戶經理，將輸入提示添加至您的帳戶。

運作方式

輸入提示 API 是一款語言預測工具——有時也被稱為自動完成或自動建議功能。根據使用者在搜尋框中輸入的部分資訊，此功能會返回區域、地點或屬性的清單。當使用者在搜尋框中輸入文字時，輸入提示 API 將開始根據城市、地區、旅宿或郵遞區號資訊，最多返回 10 項結果。旅客可從此清單中選擇項目以啟動搜尋，或繼續輸入文字以進一步精煉自動建議的結果。

例如，以「Memp」開頭的搜尋將顯示多個地理選項，包括與美國田納西州曼菲斯市相關的社區、火車站、機場等，緊接著是美國密蘇里州曼菲斯市。

啟動指南

您需要聯繫您的帳戶經理、技術帳戶經理 (TAM) 或合作夥伴解決方案經理 (PSM)，以瞭解該 API 的相關資訊。他們將申請存取權限核准，若您獲得批准，將修改您的協議以納入輸入提示。一旦為貴組織啟用輸入提示，您的技術顧問 (TAM) 或產品成功經理 (PSM) 將協助您完成任何必要的開發工作。

啟動需求：

您必須採用並使用中的不透明存取憑證驗證流程：
存取憑證僅能由請求該憑證的相同電路 ID 或 API 金鑰使用。
存取權杖僅能存在 25 分鐘。
新存取憑證的請求應設計為按該時程表進行一致性更新，且更新頻率不宜過高。
語言與請求的文本為必填參數。請參閱白標旅遊平台支援語言清單。

授權與存取

輸入提示 API 可供已升級至第 3 版的合作夥伴透過 API 端點進行請求。一旦核准，我們將為您建立一個具備成功使用 API 所需要權限的新帳戶。

建立授權

輸入提示 API 的驗證需要存取金鑰。透過授權標頭，您將提供您的 API 金鑰來呼叫 EPS 閘道，以取得存取金鑰。接著，您可透過將存取金鑰作為授權標頭傳遞，呼叫輸入提示 API 端點。

範例：將 API 金鑰以 base64 格式編碼

var api_key = postman.getEnvironmentVariable("api_key");
var shared_secret= postman.getEnvironmentVariable("shared_secret");
var base64Hash = CryptoJS.enc.Utf8.parse(api_key + ":" + shared_secret);
var base64 = CryptoJS.enc.Base64.stringify(base64Hash);
postman.setEnvironmentVariable("base64",base64);

取得不透明存取權杖

使用輸入提示 API 需具備不透明存取憑證——此類憑證不包含任何使用者或資源相關資訊。

樣本請求

POST – https://api.ean.com/identity/oauth2/v3/token 

Header: 
Key: ‘Authorization’ 
Value: ‘Basic {base64}’

範例回應

{ 

    "access_token": "p1xy6rxahicQPUIX_Sq6a52yFnHXpX3ImaSX9sKiUI4:XM8qZiTr1HPDc8FgBE5HLvFTFdICuRFV0-l7gFWI-WU", 
    "token_type": "bearer", 
    "expires_in": 1800, 
    "scope": "demand-solutions.demand-api-wrappers-playground.all" 

}

發出自動完成請求

您需要在請求標頭和查詢參數中包含一些必要資訊。為使回應更為穩健，您亦可加入可選查詢參數。

要求標頭

必要

Accept指定客戶端希望接收的回應格式。此值必須為 application/json.
Accept-Encoding指定客戶端希望接收的回應編碼。此值必須為 gzip.
User-Agent：由您的整合系統擷取自客戶請求的標頭字串。若您正在開發應用程式，則 `User-Agent ` 的值應為 `{app name}/{app version}. 例如，TravelNow/3.30.112。

查詢參數

必要

language指定回應所需語言，採用 BCP47 格式的子集，僅使用以連字號連接的雙碼組合，包含 two-digit 語言代碼與國家代碼。僅使用 ISO639-1 兩位字母語言代碼及 ISO3166-1 兩位字母國家代碼，詳見w3.org（例如：language=en-US）。請參閱支援語言清單。
text查詢輸入字串，限制為 150 個字元 (例如：text=Springfie)。
feature：變更建議結果的計算方式。值包括hierarchy、nearby_airport 以及postal_code。
line_of_business此參數提供搜尋啟發式演算法，有效值可確保回應結果更具相關性。請參閱下方的「允許值」表格以了解可用選項。

選擇性

type描述使用者正在尋找的地點。此參數可多次提供不同值 (例如：type=AIRPORT&type=CITY)。若未提供，預設值將包含所有類型。請參閱下方的「允許值」表格以了解可用選項。
region_id篩選符合指定區域的屬性結果。
origin：指定查詢文字是來源而非目的地。預設搜尋僅會尋找目的地。
package_type：根據使用者指定的套件類型進行篩選。請參閱下方的「允許值」表格以了解可用選項。
limit：指定回應中返回的建議數量的最大值。此值必須介於 1 至 10 之間 (例如：limit=5)。若未提供此參數，預設值為 10。

允許的值

type	line_of_business	package_type
`airport`	`properties` (預設)	`flight_property`
`city`	`flights`	`flight_property_car`
`multi_city_vicinity`	`packages`	`flight_car`
`neighborhood`	`cars`	`property_car`
`point_of_interest`	`activities`
`airport_metro_code`
`multi_region`
`train_station`
`metro_station`
`address`
`property`
`bus_station`

任何未包含於上表的數值都將導致錯誤。

資料請求

取得access_token 後，您將設定GET 請求。

樣本請求

GET - https://api.ean.com/v3/suggestions?language=en-US&line_of_business=properties&limit=3&text=chicago&type=city&type=neighborhood 

Header : 
Authorization: Bearer {{access_token}}

範例回應

[
  {
    "related_id": "4477519",
    "type": "airport",
    "name": "Chicago, IL (ORD-O'Hare Intl.)",
    "name_full": "Chicago, IL, United States of America (ORD-O'Hare Intl.)",
    "name_display": "<B>Chicago</B>, IL, United States of America (ORD-O'Hare Intl.)",
    "country_code": "US",
    "country_code_3": "USA",
    "iata_airport_code": "ORD",
    "iata_airport_metro_code": "CHI",
    "coordinates": {
      "latitude": 41.976977,
      "longitude": -87.90481
    }
  },
  {
    "related_id": "829",
    "type": "city",
    "name": "Chicago",
    "name_full": "Chicago, Illinois, United States of America",
    "name_display": "<B>Chicago</B>, Illinois, United States of America",
    "country_code": "US",
    "country_code_3": "USA",
    "iata_airport_code": "CHI",
    "iata_airport_metro_code": "CHI",
    "coordinates": {
      "latitude": 41.878113,
      "longitude": -87.629799
    }
  },
  {
    "related_id": "6350699",
    "type": "neighborhood",
    "name": "Downtown Chicago",
    "name_full": "Downtown Chicago, Chicago, Illinois, United States of America",
    "name_display": "Downtown <B>Chicago</B>, <B>Chicago</B>, Illinois, United States of America",
    "country_code": "US",
    "country_code_3": "USA",
    "iata_airport_code": "CHI",
    "iata_airport_metro_code": "CHI",
    "coordinates": {
      "latitude": 41.885969845574834,
      "longitude": -87.62933540465228
    }
  }
]

API 詳細資料

在這個頁面上探索相關端點的定義，然後使用 API Explorer 或其他測試軟體，了解範例和結構描述定義與實際輸出的比較。