地理
「地理 API」可讓您存取超過 600,000 個地區和機場的地理位置定義與旅宿地區定位。
地區
傳回地理位置定義，以及符合指定參數的旅宿地區定位。
若要要求全球的所有地區，請省略源始查詢參數。若要要求位於特定大陸、國家或其他層級的所有地區，請指定該地區的 ID 為源始。請參閱下方最上層地區。
地區
傳回要求之「地區 ID」的地理定義和旅宿地區定位。
使用此 API 擷取回已知「地區 ID」的地理資訊和旅宿地區定位。
取得地理定義內的旅宿
根據您的地理定義，傳回自訂多邊分界內的旅宿。
如果您有自建的地理定義，請用此 API 建構您的旅宿定位資料庫，而不要使用 Rapid 地理地區。輕鬆根據您的地理定義來對應旅宿地點，例如：多個城市、城市和地區。
搜尋篩選參數
三個搜尋參數允許進一步篩選結果，讓旅客能夠更精確的進行搜尋。
supply_source表示旅宿是來自 Expedia 或 Vrbo，如果不包含此篩選條件，則將預設為supply_source=expedia。country_code允許依照國家篩選結果，type說明城市或地區等顯示的地理實體。country_subdivision_code可將結果篩選成 ISO 3166-2 所定義的國家/地區分區。area允許按地理位置搜尋。以下有更多資訊。
其他參考資訊
地區類型
此 type 物件說明城市或地區等顯示的地理實體。如需詳細說明，請參閱「地區類型」清單。
區域
area 物件可與半徑公里，以及中間緯度/經度座標或地區邊界等合併使用。
- 結合半徑長度與
region_id可依所指定的公里數來搜尋從地區邊界向各方向延伸的範圍。 - 結合半徑長度與標好經緯度座標的定點，則可依所指定的半徑公里數畫圓搜尋某個地區。
- 半徑長度應設為非負數的整數。如輸入小數點則會出現錯誤。半徑長度可設為 0。
限制
- 設定地區參數時，會出現至多 100 個結果，還可再經由限制參數來縮減結果數量。
- 由於結果數的關係，除非將
point_of_interest指定為唯一的type，否則篩選某area的要求將不會包含point_of_interest地區類型。 - 如果同時提供
point_of_interest與其他類型，系統會忽略point_of_interest(且不會顯示錯誤訊息)，並應用所選擇的其他type。
範例：
搜尋某經緯度座標半徑 50 公里內的機場：
type=airport&limit=3&area=50,37.227924,93.310036以地區 ID 搜尋 3 至 5 公里範圍內的城市 type。
&area=5,602962&supply_score=expedia&type=city&limit=3國家/地區分區代碼
可將結果篩選至僅剩 ISO 3166-2 所定義的國家/地區分區，例如 US-MO。country_subdivision_code 既是欄位也是搜尋參數。
範例：
按 ISO 代碼進行地區搜尋：
country_subdivision_code =US-MO在地化
language 物件僅使用兩位數的語言與國家/地區代碼連字號配對，所有語言選項請參閱這裡。整合任何代碼前，請檢查我們的支援語言。在回應中僅有 name 和 name_full 欄位可依所選的語言顯示，其他所有地理定義則以英文顯示。
多邊分界
bounding_polygon 物件提供涵蓋地區形狀的座標清單。地區可涵蓋以單一多邊分界或多個多邊分界顯示的區域。地區類型若是以單一座標顯示 (例如景點、火車站、機場等等)，則不會具有多邊分界。
提供座標清單時，bounding_polygon 物件會先遵照 GeoJSON 標準中的經度值，接著再遵照緯度值。
地區間的關聯
地區間的觀光關係使用 associations 物件提供。在 associations 物件中，我們會為以下內容建立模型：
- 特定類型機場所屬地區的關聯城市。讓您能夠為任何特定機場建議目的地。
- 特定地區的熱門景點 (POI)。在旅客造訪特定地區 (如加州、倫敦或布魯克林) 時，您就能夠推薦可造訪的景點。
地區間的階層
地區間的關係使用 ancestors 與 descendants 物件提供。由於全世界的地理與政治差異使然，地區類型不具嚴格的階層關係。不過就邏輯上而言，城市通常會與多個城市、省/州或國家/地區產生關聯。若要衍生特定地區階層，請使用 ancestors 值。
ancestors表示高於指定地區的階層等級。例如，希臘雅典多個城市的直接上代為阿提卡地區，更上階則包含希臘和歐洲。一個地區可能會具有多個上代。由於日內瓦多個城市位於瑞士與法國的邊界，因此這兩個國家皆會是其上代。descendants表示低於指定地區的階層等級。例如，希臘比雷埃夫斯為希臘雅典多個城市的下代。地區物件內部的子系地圖，僅會包含該地區的直接下代 (下一階)。
tags 和 categories 使合作夥伴能夠向客戶提供有關地理特徵的更詳細資訊。
tags透過說明地理特徵在現實生活中如何命名，提供地理特徵更細部的分析。例如：活動 (滑雪、賽馬場等)、景點、市政區域或地理行政區域 (如州、教區或地區) 的說明。categories建立一個全球適用的地理特徵階層，旨在提供可對應的地理階層，無論任何特定國家或地區的政府結構為何。例如：包含大洲、國家或省。
**請注意：**擁有多個供應來源的合作夥伴，需要將供應分層到想要使用的地理區域。
範例：
"categories": [
"place:administrative",
"administrative:country"
],
"tags": [
"geo-admin:country"
]地區的旅宿定位
系統會為地區與地區 API 提供旅宿定位。具旅宿定位的地區類型為：high_level_region、state_province、multi_city_vicinity、city、neighborhood、point_of_interest，以及特定國家/地區。旅宿定位適用於兩個 include 參數選項：
property_ids：此選項僅提供地區多邊分界內部的旅宿。多邊分界為顯示地區區域的界線形狀。property_ids_expanded：若地區的多邊分界未包含至少 100 個旅宿，則此選項除了距離該地區 30 公里半徑範圍內的旅宿外，亦會提供多邊分界內部的旅宿。此擴大旅宿組合可確保在針對目的地的旅宿搜尋結果中，顯示足夠數量的旅宿。針對以單一座標而非多邊分界顯示的地區類型 (例如：景點)，僅有此擴大選項會提供關聯的旅宿定位。
多邊分界經過最佳化以使用搜尋和交易資料，並將擴展多邊分界之外最相關的較小地區。
API 詳細資料
在這個頁面上探索地理相關端點的定義，然後使用 API Explorer 或其他測試軟體，了解範例和結構描述定義與實際輸出的比較。
其他資源
無論您是想嘗試所有 Rapid API 端點，還是下載其 OpenAPI 規格或我們的 Postman Collection，我們都可協助您完成。