輸入提示快速 API

在旅行者搜尋時提供建議

Typehead (GET /suggestions) 是一個新的 API 端點，可讓您根據地理區域、相關位置和可用屬性為旅客提供建議性搜尋體驗。此端點根據部分搜尋字串和輸入的任何請求參數傳回建議清單。請聯絡您的客戶經理將輸入提示加入您的帳戶。

運作方式

輸入提示 API 是一種語言預測工具－有時也稱為自動完成或自動建議。它根據在搜尋框中輸入的部分資訊傳回區域、位置或屬性的清單。當使用者在搜尋框中輸入內容時，輸入提示 API 將開始使用城市、地區、屬性或郵遞區號資訊傳回最多 10 個結果。然後，旅行者可以從此列表中選擇以開始搜索，或繼續輸入以繼續優化自動建議的結果。

例如，以「Memp」開頭的搜尋將會看到幾個地理選項，包括與美國田納西州孟菲斯相關的街區、火車站、機場等，其次是美國密蘇裡州孟菲斯。

啟動指南

您需要聯絡您的客戶經理或 Partner Connect 代表以了解 API。他們會請求訪問批准，如果獲得批准，他們會修改您的協議以包含輸入提示。一旦您的組織啟用了輸入提示，Partner Connect 代表將為您提供任何必要的開發支援。

啟動需求：

您必須採用並使用不透明存取令牌流程進行身份驗證。
存取令牌只能由請求它的相同電路 ID 或 API 金鑰使用。
訪問令牌只能存在 25 分鐘。
應建立新的存取權杖請求，以便按照該計劃持續刷新，而不要過於頻繁地更新。
語言和請求的文字是必需參數。請參閱Rapid 支援的語言清單。

授權和存取

目前使用 Rapid 版本 3 的合作夥伴可以在 API 端點上請求 Rapid 輸入提示 API。一旦獲得批准，您現有的個人資料將擁有成功使用 API 所需的權限。

建立授權

輸入提示 API 的驗證與我們的其他 Rapid API 功能不同，因為它需要存取金鑰。使用授權標頭，您將提供您的 apikey 來呼叫 EPS 網關以取得存取金鑰。然後，您可以透過傳遞存取金鑰作為授權標頭來呼叫輸入提示 API 端點。

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

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 語言和國家代碼對。僅使用 w3.org 所描述的 ISO639-1 alpha 2 語言代碼和 ISO3166-1 alpha 2 國家/地區代碼 (例如，language=en-US)。請參閱Rapid 支援的語言清單。
text：要查詢的輸入字串，限制為 150 個字元 (例如，text=Springfie)。

選擇性

type：描述使用者正在尋找的地點。此參數可以多次提供，並帶有不同的值 (例如，type=AIRPORT&type=CITY)。如果未提供，則預設將包括所有類型。請參閱下面的允許值表以了解可用選項。
line_of_business：此參數提供搜尋啟發式方法，有效值可確保回應更加相關。雖然此參數是可選的，但省略它可能會影響搜尋結果，因此我們將預設值設為 properties。請參閱下面的允許值表以了解可用選項。
package_type：按使用者指定的包裹類型進行過濾。請參閱下面的允許值表以了解可用選項。
feature：改變建議結果的計算。數值包括 hierarchy、nearby_airport 和 postal_code。
region_id：將結果過濾為具有指定區域的屬性。
origin：指定查詢文字是否為起點而非終點。預設搜尋將僅尋找目的地。
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 與其他 Rapid API 共享常見的錯誤代碼。所有這些代碼都在我們的常見錯誤回應頁。

與其他快速 API 交互

當最終使用者在搜尋欄中輸入文字時，輸入提示 API 會根據搜尋的指定提取區域 (區域 ID、名稱、座標等) 或屬性資訊type。然後，API 會將該資訊作為結果顯示在自動完成清單中。

當使用者從自動完成清單中選擇一個區域時，將呼叫區域 API 來取得該區域周圍的屬性清單。使用從該搜尋傳回的屬性 ID 來呼叫商店 API、取得可用性並在清單中顯示屬性。

如果使用者從自動完成清單中選擇一個屬性，購物 API 將產生一個詳細資訊頁面，其中包含可用性和屬性內容的資訊。

API 詳細資料

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

其他資源

無論您是想嘗試所有 Rapid API 端點還是下載其 OpenAPI 規範或我們的 Postman 集合，我們都能滿足您的需求。