地理

Rapid Geography API 提供您存取超過 60 萬個地區和機場的地理定義及旅宿對應資訊。它包含多個子 API，供您在實作 Rapid API 時加以利用。

地區 SPI (Regions API)

如果您不確定搜尋時應使用哪個特定區域 ID，請使用 Regions API 來查找符合請求參數之區域的地理定義及旅宿對應關係。若要要求全球的所有地區，請省略源始查詢參數。若您提供祖先區域 ID，此 API 將回傳特定大陸、國家或其他層級下的所有區域。

如果您知道要搜尋的區域 ID，請使用 Region API 來取得該區域的地理定義及其對應的旅宿映射。

此 API 會根據您的地理定義，返回自訂多邊形內的屬性。如果您維護自己的地理定義，且未使用 Rapid API 中的地理區域，請使用此工具來建立您的旅宿映射資料庫。輕鬆根據您的地理定義來對應旅宿地點，例如：多個城市、城市和地區。

「type」欄位說明所代表的地理實體，例如城市或社區。如需詳細說明，請參閱「地區類型」清單。

area參數可用於指定半徑為 X 公里的範圍，並可搭配中心緯度/經度座標或區域邊界。

限制

設定地區參數時，會出現至多 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_source=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 標準在提供座標清單時，請先列出經度值，再列出緯度值。

注意： Rapid Lodging API 支援 8 KB 的資料包大小，最多可容納 2,000 組座標。

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

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

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

如需了解地理特徵的更詳細資訊，請參閱tags 及categories：

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

注意：若您的系統具備多個供應來源，您需要將它們分層疊加至您欲使用的地理區域中。

範例：

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

旅宿提供以下區域類型的對應關係：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 Explorer 或其他測試軟體，了解範例和結構描述定義與實際輸出的比較。

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