地理

Rapid Geography API 提供您存取超過 600,000 個區域與機場的地理定義及旅宿對應資訊。

地區

傳回地理位置定義，以及符合指定參數的旅宿地區定位。

若要要求全球的所有地區，請省略源始查詢參數。若要要求位於特定大陸、國家或其他層級的所有地區，請指定該地區的 ID 為源始。請參閱下方最上層地區。

地區

傳回要求之「地區 ID」的地理定義和旅宿地區定位。

使用此 API 擷取回已知「地區 ID」的地理資訊和旅宿地區定位。

取得地理定義內的旅宿

根據您的地理定義，傳回自訂多邊分界內的旅宿。

若您維護自己的地理定義且不使用 Rapid API 地理區域，請使用此 API 建立您的旅宿映射資料庫。輕鬆根據您的地理定義來對應旅宿地點，例如：多個城市、城市和地區。

搜尋篩選參數

三個搜尋參數讓旅客能進一步篩選結果，使搜尋更精準。

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物件僅使用帶連字號的 two-digit 語言與國家代碼組合，詳見可用語言選項清單。整合任何代碼前，請檢查我們的支援語言。在回應中僅有 name 和 name_full 欄位可依所選的語言顯示，其他所有地理定義則以英文顯示。

多邊分界

bounding_polygon 物件提供涵蓋地區形狀的座標清單。地區可涵蓋以單一多邊分界或多個多邊分界顯示的區域。由單一坐標代表的區域類型 (例如景點、火車站或機場) 不具備邊界多邊形。

提供座標清單時，bounding_polygon 物件會先遵照 GeoJSON 標準中的經度值，接著再遵照緯度值。

地區間的關聯

地區間的觀光關係使用 associations 物件提供。在 associations 物件中，我們會為以下內容建立模型：

特定類型機場所屬地區的關聯城市。讓您能夠為任何特定機場建議目的地。
特定區域的主要景點。這使您能夠在旅客造訪特定地區時推薦景點，例如加州、倫敦或布魯克林。

地區間的階層

地區間的關係使用 ancestors 與 descendants 物件提供。由於全世界的地理與政治差異使然，地區類型不具嚴格的階層關係。不過就邏輯上而言，城市通常會與多個城市、省/州或國家/地區產生關聯。若要衍生特定地區階層，請使用 ancestors 值。

ancestors代表特定區域上方的層級層次。例如，希臘雅典多個城市的直接上代為阿提卡地區，更上階則包含希臘和歐洲。一個地區可能會具有多個上代。由於日內瓦多個城市位於瑞士與法國的邊界，因此這兩個國家皆會是其上代。
descendants代表特定區域下方的層級層級。例如，希臘比雷埃夫斯為希臘雅典多個城市的下代。地區物件內部的子系地圖，僅會包含該地區的直接下代 (下一階)。

若需提供更詳細的地理特徵資訊，請使用tags 及categories：

tags提供更細緻的地理特徵細節，透過描述方式反映這些特徵在現實生活中的命名方式。例如：活動 (滑雪、賽馬場等)、景點、市政區域或地理行政區域 (如州、教區或地區) 的說明。
categories建立一套全球適用的地理特徵層級體系，旨在提供可比性的地理層級，無論特定國家或地區的政府結構為何。例如：包含大洲、國家或省。

註：若您的實施方案涉及多個供應來源，您需要將它們分層整合至您欲使用的地理區域中。

範例：

"categories": [
"place:administrative",
"administrative:country"
],
"tags": [
"geo-admin:country"
]

地區的旅宿定位

系統會為地區與地區 API 提供旅宿定位。具旅宿定位的地區類型為：high_level_region、province_state、multi_city_vicinity、city、neighborhood、point_of_interest，以及特定國家/地區。旅宿定位適用於兩個 include 參數選項：

property_ids：此選項僅提供地區多邊分界內部的旅宿。多邊分界為顯示地區區域的界線形狀。
property_ids_expanded：若地區的多邊分界未包含至少 100 個旅宿，則此選項除了距離該地區 30 公里半徑範圍內的旅宿外，亦會提供多邊分界內部的旅宿。此擴大旅宿組合可確保在針對目的地的旅宿搜尋結果中，顯示足夠數量的旅宿。針對以單一座標而非多邊分界顯示的地區類型 (例如：景點)，僅有此擴大選項會提供關聯的旅宿定位。

針對較大型區域類型 (high_level_region、province_state、country 及continent)，最多將返回前 500 項屬性。若要取得這些區域內所有屬性的完整清單，您需要向構成較大區域的每個子區域分別請求屬性。

多邊分界經過最佳化以使用搜尋和交易資料，並將擴展多邊分界之外最相關的較小地區。

API 詳細資料

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

其他資源

無論您是想嘗試所有 Rapid API 端點，還是下載其 OpenAPI 規格或我們的 Postman Collection，我們都可協助您完成。