Geocoder

地理編碼器 class

google.maps.Geocoder class

這項服務可將地址轉換為 LatLng，反之亦然。

撥打 const {Geocoder} = await google.maps.importLibrary("geocoding") 即可存取。
請參閱「Maps JavaScript API 中的程式庫」。

建構函式
Geocoder	Geocoder() 參數：無 建立 Geocoder 的新例項，將地理編碼要求傳送至 Google 伺服器。

方法
geocode	geocode(request[, callback]) 參數：  request：GeocoderRequest callback：function(Array<GeocoderResult> optional, GeocoderStatus): void optional 傳回值：  Promise<GeocoderResponse> 進行要求的地理編碼。

GeocoderRequest interface

google.maps.GeocoderRequest 介面

要傳送至 Geocoder 的地理編碼要求規格。

屬性
address optional	類型：  string optional 要進行地理編碼的地址。必須提供 address、location 和 placeId 其中一個，而且只能提供一個。
bounds optional	類型：  LatLngBounds|LatLngBoundsLiteral optional LatLngBounds 內搜尋。選填。
componentRestrictions optional	類型：  GeocoderComponentRestrictions optional 元件用於將結果限制在特定區域。篩選器包含一或多個下列項目：route、locality、administrativeArea、postalCode、country。系統只會傳回符合所有篩選器的結果。篩選器值與其他地理編碼要求一樣，支援相同的拼字校正及部分比對方法。選填。
extraComputations optional	注意：僅適用於 v=beta 版。 類型：  Array<ExtraGeocodeComputation> optional 可用於完成要求的額外運算清單。注意：這些額外計算可能會在回應中傳回額外欄位。
fulfillOnZeroResults optional	類型：  boolean optional 在回應中，如果狀態為 ZERO_RESULT，請履行 Promise。即使地理編碼結果為零，仍可能會傳回其他回應層級的欄位，因此可能需要這麼做。
language optional	類型：  string optional 盡可能以指定語言傳回結果的語言 ID。請參閱支援語言清單。
location optional	類型：  LatLng|LatLngLiteral optional LatLng (或 LatLngLiteral) 搜尋。地理編碼器會執行反向地理編碼。詳情請參閱「 反向地理編碼」。必須提供 address、location 和 placeId 其中一個，而且只能提供一個。
placeId optional	類型：  string optional 與該地點相關聯的地點 ID。地點 ID 可以用來辨識 Google 地點介面集資料庫和 Google 地圖中的特定地點。如要進一步瞭解地點 ID，請參閱 Places API 開發人員指南。地理編碼器會執行反向地理編碼。詳情請參閱「反向地理編碼」。必須提供 address、location 和 placeId 其中一個，而且只能提供一個。
region optional	類型：  string optional 用於調整搜尋結果的國家/地區代碼，指定為雙字元 (非數字) 萬國碼 (Unicode) 區域子標記/CLDR ID。(選用步驟) 如需支援區域的相關資訊，請參閱「Google 地圖平台涵蓋範圍詳細資料」。

GeocoderComponentRestrictions 介面

google.maps.GeocoderComponentRestrictions 介面

GeocoderComponentRestrictions 代表一組篩選器，可解析為特定區域。如要瞭解運作方式，請參閱「 地理編碼元件篩選」。

屬性
administrativeArea optional	類型：  string optional 比對所有 administrative_area levels。選填。
country optional	類型：  string optional 比對國家/地區名稱或雙字母 ISO 3166-1 國家/地區代碼。選填。
locality optional	類型：  string optional 比對 locality 和 sublocality 類型。選填。
postalCode optional	類型：  string optional 符合 postal_code 和 postal_code_prefix。選填。
route optional	類型：  string optional 比對 route 的全名或簡稱。選填。

ExtraGeocodeComputation constants

google.maps.ExtraGeocodeComputation 常數

注意：僅適用於 v=beta 版。

完成地理編碼要求時要執行的額外計算。

撥打 const {ExtraGeocodeComputation} = await google.maps.importLibrary("geocoding") 即可存取。
請參閱「Maps JavaScript API 中的程式庫」。

常數
ADDRESS_DESCRIPTORS	產生地址描述元。

GeocoderStatus 常數

google.maps.GeocoderStatus 常數

呼叫 geocode() 完成後，Geocoder 傳回的狀態。您可以依值指定這些項目，也可以使用常數名稱。例如 'OK' 或 google.maps.GeocoderStatus.OK。

撥打 const {GeocoderStatus} = await google.maps.importLibrary("geocoding") 即可存取。
請參閱「Maps JavaScript API 中的程式庫」。

常數
ERROR	與 Google 伺服器連線時發生問題。
INVALID_REQUEST	這個 GeocoderRequest 無效。
OK	回應包含有效的 GeocoderResponse。
OVER_QUERY_LIMIT	網頁已在過短的時間內超過要求限制。
REQUEST_DENIED	不允許這個網頁使用 Geocoder。
UNKNOWN_ERROR	伺服器發生錯誤，因此無法處理地理編碼要求。如果您再試一次，該要求可能會成功。
ZERO_RESULTS	找不到「GeocoderRequest」的結果。

GeocoderResponse 介面

google.maps.GeocoderResponse 介面

Geocoder 傳回的地理編碼器回應，內含 GeocoderResult 清單。

屬性
results	類型：  Array<GeocoderResult> GeocoderResult 清單。
address_descriptor optional	注意：僅適用於 v=beta 版。 類型：  AddressDescriptor optional 地點的相關說明。包括附近地標的排名組合，以及包含目標位置的區域。系統只會針對反向地理編碼要求填入適當值，且僅限啟用 ExtraGeocodeComputation.ADDRESS_DESCRIPTORS 時。
plus_code optional	類型：  PlacePlusCode optional 與該地點相關聯的 Plus Code。

GeocoderResult interface

google.maps.GeocoderResult 介面

擷取自地理編碼伺服器的單一 Geocoder 結果。地理編碼要求可能會傳回多個結果物件。請注意，雖然這個結果「類似 JSON」，但並非嚴格意義上的 JSON，因為它間接包含 LatLng 物件。

屬性
address_components	類型：  Array<GeocoderAddressComponent> GeocoderAddressComponent 陣列
formatted_address	類型：  string 字串，內含這個地點的人類可讀地址。
geometry	類型：  GeocoderGeometry GeocoderGeometry 物件
place_id	類型：  string 與該地點相關聯的地點 ID。地點 ID 可以用來辨識 Google 地點介面集資料庫和 Google 地圖中的特定地點。如要進一步瞭解地點 ID，請參閱 Places API 開發人員指南。
types	類型：  Array<string> 註明傳回地理編碼元素類型的字串陣列。如需可能字串的清單，請參閱《開發人員指南》的「 地址元件類型」一節。
address_descriptor optional	注意：僅適用於 v=beta 版。 類型：  AddressDescriptor optional 與這個地理編碼相關聯的地點關係說明。包括附近地標的排名組合，以及包含目標位置的區域。只有在啟用 ExtraGeocodeComputation.ADDRESS_DESCRIPTORS 時，系統才會填入這個欄位，且僅適用於正向地理編碼和地點 ID 查詢要求，以及特定本地化地點。
partial_match optional	類型：  boolean optional 地理編碼器沒有傳回與原始要求完全相符的結果，但可以比對部分要求的地址。如果完全相符，值會是 undefined。
plus_code optional	類型：  PlacePlusCode optional 與該地點相關聯的 Plus Code。
postcode_localities optional	類型：  Array<string> optional 字串陣列，表示郵遞區號內含的所有縣市。系統只會在所傳回結果是包含多個位置的郵遞區號時，才會顯示這個陣列。

AddressDescriptor 介面

google.maps.AddressDescriptor 介面

注意：僅適用於 v=beta 版。

地點的相關說明。包括附近地標的排名組合，以及包含目標位置的區域。

屬性
areas	類型：  Array<Area> 包含或相鄰區域的排名清單。系統會優先顯示最實用 (可辨識且精確) 的區域。
landmarks	類型：  Array<Landmark> 附近地標的排序清單。系統會優先列出最實用的地標 (可辨識且位於附近)。

GeocoderAddressComponent 介面

google.maps.GeocoderAddressComponent 介面

GeocoderResult 中的單一地址元件。完整的地址可能包含多個地址元件。

屬性
long_name	類型：  string 地址元件的全文
short_name	類型：  string 指定地址元件的縮寫文字
types	類型：  Array<string> 字串陣列，表示這個地址元件的類型。如要查看有效類型清單，請按這裡

GeocoderGeometry 介面

google.maps.GeocoderGeometry 介面

這個 GeocoderResult 的幾何資訊

屬性
location	類型：  LatLng 這個結果的緯度/經度座標
location_type	類型：  GeocoderLocationType location 中傳回的地點類型
viewport	類型：  LatLngBounds 顯示此 GeocoderResult 的建議可視區域邊界
bounds optional	類型：  LatLngBounds optional 這個 GeocoderResult 的精確界線 (如適用)

GeocoderLocationType 常數

google.maps.GeocoderLocationType 常數

說明從地理編碼傳回的位置類型。您可以依值指定這些項目，也可以使用常數名稱。例如 'ROOFTOP' 或 google.maps.GeocoderLocationType.ROOFTOP

撥打 const {GeocoderLocationType} = await google.maps.importLibrary("geocoding") 即可存取。
請參閱「Maps JavaScript API 中的程式庫」。

常數
APPROXIMATE	傳回的結果是約略的。
GEOMETRIC_CENTER	傳回的結果為一條線 (例如街道) 或多邊形 (區域) 結果的地理中心點。
RANGE_INTERPOLATED	傳回結果反映了插入在兩個精確點之間 (例如十字路口) 的約略位置 (通常是在道路上)。如果 Geocoder 無法取得街道地址的精確定點地理編碼，就會傳回插入的結果。
ROOFTOP	傳回的結果反映精確的地理編碼。

地標 介面

google.maps.Landmark 介面

注意：僅適用於 v=beta 版。

代表地址參考點的地點。

屬性
display_name	類型：  string 地標的名稱。
display_name_language_code	類型：  string 地標名稱的語言。
place_id	類型：  string 做為地標的基礎機構地點 ID。可用於透過 Place Details 或 Place Id Lookup 解決地標的詳細資訊。
spatial_relationship	類型：  SpatialRelationship 定義目標位置與地標之間的空間關係。
straight_line_distance_meters	類型：  number 目標位置與地標之間的直線距離。
types	類型：  Array<string> 一或多個值，指出傳回結果的類型。詳情請參閱「類型 」。
travel_distance_meters optional	類型：  number optional 目標位置與地標之間沿道路網路的行車距離。如果地標與目標最接近的路網部分中斷連線，或者目標位置實際上並未視為位於路網上，則這項資訊可能不會填入。

區域 介面

google.maps.Area 介面

注意：僅適用於 v=beta 版。

小型區域，例如鄰里、次區域，或包含目標位置的大型建築群。

屬性
containment	類型：  Containment 定義目標位置與區域之間的空間關係。
display_name	類型：  string 區域名稱。
display_name_language_code	類型：  string 區域名稱的語言。
place_id	類型：  string 基礎區域的地點 ID。可用於透過 Place Details 或 Place ID Lookup 解決區域的更多資訊。

封裝 常數

google.maps.Containment 常數

注意：僅適用於 v=beta 版。

列舉，代表區域與目標位置之間的空間關係。

撥打 const {Containment} = await google.maps.importLibrary("geocoding") 即可存取。
請參閱「Maps JavaScript API 中的程式庫」。

常數
NEAR	目標位置不在區域範圍內，但距離不遠。
OUTSKIRTS	目標位置位於區域內，靠近邊緣。
WITHIN	目標位置位於區域內，靠近中心。

SpatialRelationship 常數

google.maps.SpatialRelationship 常數

注意：僅適用於 v=beta 版。

列舉，代表地標和目標在空間中的關係。

撥打 const {SpatialRelationship} = await google.maps.importLibrary("geocoding") 即可存取。
請參閱「Maps JavaScript API 中的程式庫」。

常數
ACROSS_THE_ROAD	目標位於道路另一側，與地標正對面。
AROUND_THE_CORNER	不在地標的同一條路徑上，但只要轉個彎就能抵達。
BEHIND	靠近地標建築，但距離出入口較遠。
BESIDE	目標直接位於地標旁。
DOWN_THE_ROAD	與地標位於同一條路線上，但不在地標旁邊或對面。
NEAR	如果以下沒有更具體的關係，這就是預設關係。
WITHIN	地標具有空間幾何圖形，且目標位於地標範圍內。