公告：Google 地圖平台即將推出新版基本地圖樣式。新版地圖樣式內建全新的預設調色盤、現代化的圖釘，並且提升地圖體驗、改善服務的可用性。所有地圖樣式都將於 2025 年 3 月自動更新。請參閱「Google 地圖平台新版地圖樣式」一文，進一步瞭解適用範圍及如何提早啟用。

本頁面由 Cloud Translation API 翻譯而成。

Geocoder

Geocoder 類別

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 介面

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`。系統只會傳回符合所有篩選器的結果。篩選器值與其他地理編碼要求一樣，支援相同的拼字校正及部分比對方法。選填。
`language optional`	類型： `string optional` 語言 ID，用於指定應傳回結果的語言 (如有可能)。請參閱支援語言清單。
`location optional`	類型： `LatLng\|LatLngLiteral optional` `LatLng` (或 `LatLngLiteral`) 的搜尋值。地理編碼器會執行反向地理編碼。詳情請參閱「反向地理編碼」。必須提供 `address`、`location` 和 `placeId` 其中一個，且只能提供一個。
`placeId optional`	類型： `string optional` 與位置相關聯的地點 ID。地點 ID 可以用來辨識 Google 地點介面集資料庫和 Google 地圖中的特定地點。如要進一步瞭解 Place 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` 的全名或簡稱。選填。

GeocoderStatus 常數

google.maps.GeocoderStatus 常數

Geocoder 在完成對 geocode() 的呼叫時傳回的狀態。您可以使用值或常數名稱來指定這些值。例如 '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` 清單。

GeocoderResult 介面

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 地圖中的特定地點。如要進一步瞭解 Place ID，請參閱 Places API 開發人員指南。
`types`	類型： `Array<string>` 註明傳回地理編碼元素類型的字串陣列。如需可能字串的清單，請參閱開發人員指南的「地址元件類型」一節。
`partial_match optional`	類型： `boolean optional` 地理編碼器是否未傳回與原始要求完全相符的結果，但可以比對部分要求的地址。如果完全比對成功，值會是 `undefined`。
`plus_code optional`	類型： `PlacePlusCode optional` 與位置相關聯的 Plus Code。
`postcode_localities optional`	類型： `Array<string> optional` 字串陣列，表示郵遞區號內含的所有縣市。系統只會在所傳回結果是包含多個位置的郵遞區號時，才會顯示這個陣列。

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`	傳回的結果反映精確的地理編碼。