地理編碼服務

總覽

地理編碼是指將地址 (例如 1600 Amphitheatre Parkway, Mountain View, CA) 轉換成地理座標 (例如緯度 37.423021 和經度 -122.083739) 的程序,您可以透過這項程序放置標記或在地圖上定位。

反向地理編碼是指將地理座標轉換為人類可讀地址的程序 (請參閱「反向地理編碼 (地址查詢)」一文)。

您也可以使用地理編碼器,找出特定地點 ID 的地址。

Maps JavaScript API 提供地理編碼器類別,可針對使用者輸入的地址以動態方式進行地理編碼或反向地理編碼。如要改為針對已知靜態地址進行地理編碼,請參閱「地理編碼網路服務」一文。

開始使用

請先確認在 Google Cloud 控制台中,針對您為 Maps JavaScript API 設定的同一個專案啟用 Geocoding API,再使用 Maps JavaScript API 中的地理編碼服務。

如要查看已啟用的 API 清單,請按照下列步驟操作:

  1. 前往 Google Cloud 控制台
  2. 按一下「選取專案」按鈕,選取同一個針對 Maps JavaScript API 設定的專案,然後點選「開啟」
  3. 在「資訊主頁」的 API 清單中,找出 Geocoding API
  4. 如果在清單中看到該 API,就表示一切就緒。如果「沒有」看到這個 API,請按照下列步驟進行啟用:
    1. 選取頁面頂端的「ENABLE API」(啟用 API),即會顯示「Library」(程式庫) 分頁。或者,您也可以從左側選單中選取「程式庫」
    2. 搜尋「Geocoding API」,然後從結果清單中選取該 API。
    3. 選取「啟用」。這個程序完成後,「資訊主頁」的 API 清單就會顯示「Geocoding API」

定價和政策

定價

自 2018 年 7 月 16 日起,地圖介面集、路徑介面集和地點介面集採用新的「即付即用」定價方案,如要進一步瞭解新的 JavaScript 地理編碼服務使用費和用量限制,請參閱 Geocoding API 的「用量與計費」一文。

政策

使用地理編碼服務時,必須遵守 Geocoding API 的既定政策

地理編碼要求

Google Maps API 必須呼叫外部伺服器,因此地理編碼服務是以非同步的方式存取。基於這個理由,您必須傳遞在完成要求後執行的「回呼」方法。這個回呼方法會處理結果。請注意,地理編碼器可能會傳回多筆結果。

您可以透過 google.maps.Geocoder 建構函式物件,在程式碼內存取 Google Maps API 地理編碼服務。Geocoder.geocode() 方法會向地理編碼服務發出要求,並將含有輸入字詞的 GeocoderRequest 物件常值,以及收到回應後要執行的回呼方法傳遞至該服務。

GeocoderRequest 物件常值包含下列欄位:

{
 address: string,
 location: LatLng,
 placeId: string,
 bounds: LatLngBounds,
 componentRestrictions: GeocoderComponentRestrictions,
 region: string
}

必要參數:您必須擇一提供下列欄位:

  • address:您要進行地理編碼的地址。
        
    location:用於取得距離最近且人類可讀地址的 LatLng (或 LatLngLiteral)。地理編碼器會執行「反向地理編碼」。詳情請參閱「反向地理編碼」一文。
        
    placeId:用於取得距離最近且人類可讀地址的地點 ID。進一步瞭解如何擷取地點 ID 的地址

自選參數:

  • boundsLatLngBounds,您可在此範圍內進一步調整地理編碼結果。bounds 參數只會影響但不會完全限制地理編碼器提供的結果。詳情請參閱下方「可視區域自訂調整」一節。
  • componentRestrictions:用於將結果限制在特定區域。詳情請參閱下方「元件篩選」一節。
  • region:區碼,指定為雙字元 (非數字) 萬國碼 (Unicode) 區域子標記。在大多數情況下,這些標記會直接對應到熟悉的 ccTLD (「頂層網域」) 雙字元值。region 參數只會影響但不會完全限制地理編碼器提供的結果。詳情請參閱下方「區碼自訂調整」一節。

地理編碼回應

地理編碼服務需要一個在擷取地理編碼器結果後執行的回呼方法。這個回呼方法必須傳遞兩個參數,以依序保存 resultsstatus 代碼。

地理編碼結果

GeocoderResult 物件表示單筆地理編碼結果。地理編碼要求可能會傳回多個結果物件:

results[]: {
 types[]: string,
 formatted_address: string,
 address_components[]: {
   short_name: string,
   long_name: string,
   postcode_localities[]: string,
   types[]: string
 },
 partial_match: boolean,
 place_id: string,
 postcode_localities[]: string,
 geometry: {
   location: LatLng,
   location_type: GeocoderLocationType
   viewport: LatLngBounds,
   bounds: LatLngBounds
 }
}

這些欄位的說明如下:

  • types[] 是一個陣列,用來指出傳回結果的「地址類型」。這個陣列不含任何標記或包含多個標記的組合,用於識別結果中傳回的地圖項目類型。舉例來說,「台北」的地理編碼會傳回「縣市」,指出「台北」是一個城市,並傳回「政治」,指出這是一個政治實體。詳情請參閱下方「地址類型和地址元件類型」一節。
  • formatted_address 字串包含這個地點的人類可讀地址。

    這個地址通常等於郵寄地址。請注意,由於授權上的限制,部分國家/地區 (例如英國) 不允許散布真實的郵寄地址。

    理論上,格式化地址是由一或多個「地址元件」組成。舉例來說,「111 8th Avenue, New York, NY」這個地址包含以下元件:「111」(門牌號碼)、「8th Avenue」(路名)、「New York」(城市) 和「NY」(美國州名)。

    請勿以程式輔助方式剖析格式化地址。建議您改用個別地址元件,API 回應除了包含格式化地址欄位之外,也會包含這些元件。

  • address_components[] 陣列包含這個地址適用的各種元件。

    每個地址元件通常會包含下列欄位:

    • types[] 是一個陣列,用來指出地址元件的「類型」。請參閱支援類型清單。
    • long_name 是地理編碼器所傳回地址元件的完整文字說明或名稱。
    • short_name 是地址元件的縮寫文字名稱 (如有)。舉例來說,阿拉斯加州地址元件的 long_name 可能為「Alaska」,而 short_name 則為 2 個字母的郵政簡碼「AK」。

    address_components[] 陣列的注意事項如下:

    • 地址元件陣列包含的元件可能比 formatted_address 更多。
    • 除了 formatted_address 中所含的政治實體以外,這個陣列不一定會納入內含地址的所有政治實體。如要擷取包含特定地址的所有政治實體,建議您使用反向地理編碼,將地址的經緯度做為參數傳遞至要求。
    • 兩次要求之間的回應格式不一定相同。特別是,address_components 的數量會因要求的地址而異,對於同一個地址,數量也可能會隨時間改變。元件在陣列中的位置可能會變更。元件類型也可能會變更。後續回應中可能會缺少特定元件。

    詳情請參閱下方「地址類型和地址元件類型」一節。

  • partial_match 指出地理編碼器沒有傳回與原始要求完全相符的結果,但可以比對部分要求的地址。建議您檢查原始要求,確認是否有拼寫錯誤和/或不完整的地址。

    出現部分相符結果的最常見原因,是系統在要求中傳遞的縣市內找不到街道地址。如果要求比對同一個縣市內的兩個或更多地點,也可能會傳回部分相符的結果。舉例來說,「Hillpar St, Bristol, UK」會傳回 Henry Street 和 Henrietta Street 這兩項部分相符的結果。請注意,如果要求包含拼寫錯誤的地址元件,地理編碼服務可能就會建議使用替代地址。透過這種方式觸發的建議,也會標示為部分相符。

  • place_id 是地點的專屬 ID,可與其他 Google API 搭配使用。舉例來說,您可以搭配 Google Places API 程式庫使用 place_id,以取得當地商家的詳細資料,例如電話號碼、營業時間和使用者評論等等。請參閱地點 ID 總覽
  • postcode_localities[] 陣列表示郵遞區號內含的所有縣市,且只有在結果是包含多個縣市的郵遞區號時才會顯示。
  • geometry 包含下列資訊:

    • location 包含經過地理編碼的經緯度值。請注意,我們會以 LatLng 物件 (而非格式化字串) 傳回這個位置。
    • location_type 會儲存指定位置的其他相關資料,以下是目前支援的值:
      • ROOFTOP 表示傳回結果反映了精確的地理編碼。
      • RANGE_INTERPOLATED 表示傳回結果反映了插入在兩個精確點之間 (例如十字路口) 的約略位置 (通常是在道路上)。如果街道地址沒有精準的地理編碼,系統通常就會傳回插入的結果。
      • GEOMETRIC_CENTER 表示傳回結果是結果的幾何圖形中心,包括折線 (例如街道) 或多邊形 (區域)。
      • APPROXIMATE 表示傳回結果是約略位置。

    • viewport 會儲存傳回結果的建議可視區域。
    • bounds (選擇性傳回) 會儲存可完全涵蓋傳回結果的 LatLngBounds。請注意,這些邊界可能與建議可視區域不符 (舉例來說,舊金山行政區包括法拉隆群島,雖然該群島嚴格來說是舊金山的一部分,但不應在可視區域中傳回)。

地理編碼器傳回地址時會採用瀏覽器的偏好語言設定,或是 language 參數載入 API JavaScript 時指定的語言 (詳情請參閱「本地化」一文)。

地址類型和地址元件類型

GeocoderResult 中的 types[] 陣列表示「地址類型」GeocoderAddressComponent 內也可能會傳回 types[] 陣列,表示特定位址元件的類型。地理編碼器傳回的地址可能包含多種類型,這些類型可視為標記。舉例來說,許多城市都會加上 politicallocality 類型標記。

在地址類型和地址元件類型中,地理編碼器會支援及傳回下列類型:

  • street_address 表示精確的街道地址。
  • route 表示具名道路 (例如「國道一號」)。
  • intersection 表示主要的十字路口,通常有兩條主要道路交會。
  • political 表示政治實體。這個類型通常表示某些行政管理區的多邊形區域。
  • country 表示國家政治實體,且通常是地理編碼器所傳回的最高順位類型。
  • administrative_area_level_1 表示國家/地區層級底下的第一順位行政實體。在美國境內,這類行政層級是指州。部分國家沒有這類行政層級。在大多數情況下,administrative_area_level_1 簡稱會與 ISO 3166-2 子行政區以及其他廣泛流通的清單密切相符。然而,地理編碼結果是根據多種信號和位置資料計算得出,因此我們對於結果無法做出保證。
  • administrative_area_level_2 表示國家/地區層級底下的第二順位行政實體。在美國境內,這類行政層級是指郡。部分國家沒有這類行政層級。
  • administrative_area_level_3 表示國家/地區層級底下的第三順位行政實體。這個類型表示小型行政單位。部分國家沒有這類行政層級。
  • administrative_area_level_4 表示國家/地區層級底下的第四順位行政實體。這個類型表示小型行政單位。部分國家沒有這類行政層級。
  • administrative_area_level_5 表示國家/地區層級底下的第五順位行政實體。這個類型表示小型行政單位。部分國家沒有這類行政層級。
  • administrative_area_level_6 表示國家/地區層級底下的第六順位行政實體。這個類型表示小型行政單位。部分國家沒有這類行政層級。
  • administrative_area_level_7 表示國家/地區層級底下的第七順位行政實體。這個類型表示小型行政單位。部分國家沒有這類行政層級。
  • colloquial_area 表示實體的常用替代名稱。
  • locality 表示自治城市或鄉鎮的政治實體。
  • sublocality 表示縣市底下的第一順位行政實體。某些地點可能會收到以下其中一種額外類型:sublocality_level_1sublocality_level_5。每個鄉鎮市區層級都是一個行政實體。數字越大表示地理區域越小。
  • neighborhood 表示具名社區
  • premise 表示具名地點,通常是建築物或具有共同名稱的建築物群
  • subpremise 表示具名地點底下的第一順位實體,通常是具有共同名稱的建築物群中的單一建築物
  • plus_code 表示經過編碼的位置參照,衍生自經緯度。對於沒有詳細地址的地點,Plus Codes 可用於取代街道地址,例如無編號的建築物或無名街道。詳情請參閱 https://plus.codes
  • postal_code 表示國家/地區郵政地址所使用的郵遞區號。
  • natural_feature 表示明顯的自然地貌。
  • airport 表示機場。
  • park 表示具名公園。
  • point_of_interest 表示具名搜尋點。一般來說,這些「搜尋點」是當地著名的實體,無法輕易歸入其他類別,例如「帝國大廈」或「艾菲爾鐵塔」。

如果類型清單為空白,表示特定地址元件沒有已知的類型 (例如法國的 Lieu-dit)。

除了上述類型以外,地址元件也可能含有以下類型。

注意:這份清單並不完整,可能會隨時變更。

  • floor 表示建築物地址的樓層。
  • establishment 通常表示尚未歸類的地點。
  • landmark 表示附近地點,做為導航輔助參考。
  • point_of_interest 表示具名搜尋點。
  • parking 表示停車場。
  • post_box 表示特定郵政信箱。
  • postal_town 表示地理區域分組 (例如 localitysublocality),在部分國家/地區用於郵寄地址。
  • room 表示建築物地址的房號。
  • street_number 表示精確的門牌號碼。
  • bus_stationtrain_stationtransit_station 表示公車、火車或大眾運輸停靠站的位置。

狀態碼

status 代碼可能會傳回下列其中一個值:

  • "OK" 表示沒有發生任何錯誤。地址剖析成功,且系統傳回至少一組地理編碼。
  • "ZERO_RESULTS" 表示地理編碼成功,但沒有傳回任何結果。如果地理編碼器收到不存在的 address,就有可能發生這種情況。
  • "OVER_QUERY_LIMIT" 表示您已超過配額。
  • "REQUEST_DENIED" 表示您的要求遭拒。這個網頁禁止使用地理編碼器。
  • "INVALID_REQUEST" 通常表示缺少查詢內容 (addresscomponentslatlng)。
  • "UNKNOWN_ERROR" 表示伺服器發生錯誤,因此無法處理要求。如果再試一次,要求可能會成功。
  • "ERROR" 表示要求逾時,或是聯繫 Google 伺服器時發生問題。如果再試一次,要求可能會成功。

在本例中,我們會針對地址進行地理編碼,並為傳回的經緯度值加上標記。請注意,我們會以匿名函式常值的形式傳遞處理常式。

  var geocoder;
  var map;
  function initialize() {
    geocoder = new google.maps.Geocoder();
    var latlng = new google.maps.LatLng(-34.397, 150.644);
    var mapOptions = {
      zoom: 8,
      center: latlng
    }
    map = new google.maps.Map(document.getElementById('map'), mapOptions);
  }

  function codeAddress() {
    var address = document.getElementById('address').value;
    geocoder.geocode( { 'address': address}, function(results, status) {
      if (status == 'OK') {
        map.setCenter(results[0].geometry.location);
        var marker = new google.maps.Marker({
            map: map,
            position: results[0].geometry.location
        });
      } else {
        alert('Geocode was not successful for the following reason: ' + status);
      }
    });
  }

<body onload="initialize()">
 <div id="map" style="width: 320px; height: 480px;"></div>
  <div>
    <input id="address" type="textbox" value="Sydney, NSW">
    <input type="button" value="Encode" onclick="codeAddress()">
  </div>
</body>

查看範例

可視區域自訂調整

您可以指示地理編碼服務優先顯示指定可視區域 (以定界框表示) 內的結果,方法是設定 GeocoderRequest 物件常值內的 bounds 參數,藉此定義這個可視區域的邊界。請注意,自訂調整功能只是「優先」顯示邊界內的結果,如果邊界外有更相關的結果,可能也會一併納入。

舉例來說,「Winnetka」的地理編碼通常會傳回芝加哥的「Winnetka」郊區:

{
  "types":["locality","political"],
  "formatted_address":"Winnetka, IL, USA",
  "address_components":[{
    "long_name":"Winnetka",
    "short_name":"Winnetka",
    "types":["locality","political"]
  },{
    "long_name":"Illinois",
    "short_name":"IL",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"United States",
    "short_name":"US",
    "types":["country","political"]
  }],
  "geometry":{
    "location":[ -87.7417070, 42.1083080],
    "location_type":"APPROXIMATE"
  },
  "place_id": "ChIJW8Va5TnED4gRY91Ng47qy3Q"
}

不過,如果我們透過指定 bounds 參數的方式,將定界框定義在洛杉磯的聖佛南多谷,那麼這個地理編碼將會傳回該位置的「Winnetka」社區:

{
  "types":["sublocality","political"],
  "formatted_address":"Winnetka, California, USA",
  "address_components":[{
    "long_name":"Winnetka",
    "short_name":"Winnetka",
    "types":["sublocality","political"]
  },{
    "long_name":"Los Angeles",
    "short_name":"Los Angeles",
    "types":["administrative_area_level_3","political"]
  },{
    "long_name":"Los Angeles",
    "short_name":"Los Angeles",
    "types":["administrative_area_level_2","political"]
  },{
    "long_name":"California",
    "short_name":"CA",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"United States",
    "short_name":"US",
    "types":["country","political"]
  }],
  "geometry":{
    "location": [34.213171,-118.571022],
    "location_type":"APPROXIMATE"
  },
  "place_id": "ChIJ0fd4S_KbwoAR2hRDrsr3HmQ"
}

區碼自訂調整

您可以使用 region 參數,讓地理編碼服務優先傳回特定區域的結果。這個參數會採用指定為雙字元 (非數字) 萬國碼 (Unicode) 區域子標記的區碼。這些標記會直接對應到熟悉的 ccTLD (「頂層網域」) 雙字元值,例如「co.uk」的「uk」。而在某些情況下,region 標記也支援 ISO-3166-1 代碼,這種代碼有時會與 ccTLD 值不同 (例如「GB」代表「Great Britain」)。

使用 region 參數時:

  • 請只指定一個國家/地區。如果超過一個,除了會遭到忽略以外,還可能會導致要求失敗。
  • 請只使用兩位字元區域子標記 (萬國碼 (Unicode) CLDR 格式),所有其他輸入內容都會導致錯誤。
  • 系統僅支援 Google 地圖平台涵蓋範圍詳細資料中所列的國家/地區和區域。

只要是主要 Google 地圖應用程式提供地理編碼的網域,都可以傳送地理編碼要求。請注意,自訂調整功能只是「優先」採用特定網域的結果,如果網域外有更相關的結果,可能也會一併納入。

舉例來說,地理編碼服務的預設網域為美國,因此「Toledo」的地理編碼會傳回以下結果:

{
  "types":["locality","political"],
  "formatted_address":"Toledo, OH, USA",
  "address_components":[{
    "long_name":"Toledo",
    "short_name":"Toledo",
    "types":["locality","political"]
  },{
    "long_name":"Ohio",
    "short_name":"OH",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"United States",
    "short_name":"US",
    "types":["country","political"]
  }],
  "place_id": "ChIJeU4e_C2HO4gRRcM6RZ_IPHw"
}

如果將 region 欄位設為 'es' (西班牙),「Toledo」的地理編碼就會傳回西班牙的城市:

{
  "types":["locality","political"],
  "formatted_address":"Toledo, España",
  "address_components":[{
    "long_name":"Toledo",
    "short_name":"Toledo",
    "types":["locality","political"]
  },{
    "long_name":"Toledo",
    "short_name":"TO",
    "types":["administrative_area_level_2","political"]
  },{
    "long_name":"Castilla-La Mancha",
    "short_name":"CM",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"España",
    "short_name":"ES",
    "types":["country","political"]
  }],
  "place_id": "ChIJ8f21C60Lag0R_q11auhbf8Y"
}

元件篩選

您可以使用元件篩選器,將地理編碼服務設為只傳回特定區域的地址結果。請在 componentRestrictions 參數中指定篩選器。篩選器值支援的拼字校正和部分比對方法與其他地理編碼要求相同。

地理編碼器只會傳回與所有元件篩選器相符的結果。也就是說,地理編碼器會將篩選器規格視為「且」,而不是「或」。

元件篩選器包含下列一或多個項目:

  • route 用於比對道路的全名或簡稱。
  • locality 用於比對縣市和鄉鎮市區類型。
  • administrativeArea 用於比對所有行政區層級。
  • postalCode 用於比對郵遞區號和郵遞區號首碼。
  • country 用於比對國家/地區名稱或雙字母 ISO 3166-1 國家/地區代碼。注意:API 遵循 ISO 標準來定義國家/地區,因此使用國家/地區的相應 ISO 代碼時,篩選功能的效果最佳。

下例示範如何使用 componentRestrictions 參數,依 countrypostalCode 進行篩選:

function codeAddress() {
geocoder.geocode({
  componentRestrictions: {
    country: 'AU',
    postalCode: '2000'
  }
}, function(results, status) {
  if (status == 'OK') {
    map.setCenter(results[0].geometry.location);
    var marker = new google.maps.Marker({
      map: map,
      position: results[0].geometry.location
    });
  } else {
    window.alert('Geocode was not successful for the following reason: ' + status);
  }
});
}

反向地理編碼 (地址查閱)

「地理編碼」一詞通常是指將清楚易懂的地址轉譯成地圖上的某個位置。而這項程序的反向作業 (將地圖上的某個位置轉譯成清楚易懂的地址),就稱為「反向地理編碼」

請在 location 參數中提供以半形逗號分隔的經緯度組合,不要提供文字的 address

下例會針對經緯度值進行地理編碼,並將地圖中心移至該位置,然後開啟資訊視窗來顯示格式化地址。

TypeScript

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 8,
      center: { lat: 40.731, lng: -73.997 },
    }
  );
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  (document.getElementById("submit") as HTMLElement).addEventListener(
    "click",
    () => {
      geocodeLatLng(geocoder, map, infowindow);
    }
  );
}

function geocodeLatLng(
  geocoder: google.maps.Geocoder,
  map: google.maps.Map,
  infowindow: google.maps.InfoWindow
) {
  const input = (document.getElementById("latlng") as HTMLInputElement).value;
  const latlngStr = input.split(",", 2);
  const latlng = {
    lat: parseFloat(latlngStr[0]),
    lng: parseFloat(latlngStr[1]),
  };

  geocoder
    .geocode({ location: latlng })
    .then((response) => {
      if (response.results[0]) {
        map.setZoom(11);

        const marker = new google.maps.Marker({
          position: latlng,
          map: map,
        });

        infowindow.setContent(response.results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;

JavaScript

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 8,
    center: { lat: 40.731, lng: -73.997 },
  });
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  document.getElementById("submit").addEventListener("click", () => {
    geocodeLatLng(geocoder, map, infowindow);
  });
}

function geocodeLatLng(geocoder, map, infowindow) {
  const input = document.getElementById("latlng").value;
  const latlngStr = input.split(",", 2);
  const latlng = {
    lat: parseFloat(latlngStr[0]),
    lng: parseFloat(latlngStr[1]),
  };

  geocoder
    .geocode({ location: latlng })
    .then((response) => {
      if (response.results[0]) {
        map.setZoom(11);

        const marker = new google.maps.Marker({
          position: latlng,
          map: map,
        });

        infowindow.setContent(response.results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

window.initMap = initMap;
查看範例

測試範例程式碼

請注意,在前一個範例中,我們選取 results[0] 來顯示第一筆結果。反向地理編碼器通常會傳回多筆結果。經過地理編碼的地址不僅是郵寄地址,也可以使用任何表述地理的方式為地點命名。舉例來說,針對芝加哥市的某個定點進行地理編碼時,這個地理編碼定點可以標示為街道地址、城市 (芝加哥)、州名 (伊利諾州) 或國家/地區 (美國)。對地理編碼器而言,這些都是地址。反向地理編碼器會將這些結果全部傳回。

反向地理編碼器會比對政治實體 (國家/地區、州/省、城市和社區)、街道地址和郵遞區號。

以下例舉上述查詢可能傳回的地址清單:

results[0].formatted_address: "277 Bedford Ave, Brooklyn, NY 11211, USA"
results[1].formatted_address: "Grand St/Bedford Av, Brooklyn, NY 11211, USA"
results[2].formatted_address: "Williamsburg, Brooklyn, NY, USA"
results[3].formatted_address: "Brooklyn, NY, USA"
results[4].formatted_address: "New York, NY, USA"
results[5].formatted_address: "Brooklyn, NY 11211, USA"
results[6].formatted_address: "Kings County, NY, USA"
results[7].formatted_address: "New York-Northern New Jersey-Long Island, NY-NJ-PA, USA"
results[8].formatted_address: "New York Metropolitan Area, USA"
results[9].formatted_address: "New York, USA"

系統會根據相符程度傳回地址 (最相符到最不相符)。一般來說,最相符的地址是最顯眼的結果,如本例所示。請注意,我們會傳回各種地址,從最具體的街道地址到較籠統的政治實體,例如社區、城市、郡/縣、州/省等。如要與較籠統的地址達成比對,建議您查看 results[].types 欄位。

注意:反向地理編碼並非完全精準。地理編碼器會在容許的範圍內,嘗試找出最接近的地址位置。

擷取地點 ID 的地址

提供 placeId 即可找出特定地點 ID 的地址。地點 ID 是一組專屬 ID,可與其他 Google API 搭配使用。舉例來說,您可以提供 Roads API 傳回的 placeId,以取得對齊點的地址。如要進一步瞭解地點 ID,請參閱地點 ID 總覽

提供 placeId 時,要求不得包含下列任一欄位:

  • address
  • latLng
  • location
  • componentRestrictions

下例會接受地點 ID、找出對應的地址,然後將地圖中心移至該位置。此外,其中也會開啟資訊視窗來顯示相關地點的格式化地址:

TypeScript

// Initialize the map.
function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 8,
      center: { lat: 40.72, lng: -73.96 },
    }
  );
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  (document.getElementById("submit") as HTMLElement).addEventListener(
    "click",
    () => {
      geocodePlaceId(geocoder, map, infowindow);
    }
  );
}

// This function is called when the user clicks the UI button requesting
// a geocode of a place ID.
function geocodePlaceId(
  geocoder: google.maps.Geocoder,
  map: google.maps.Map,
  infowindow: google.maps.InfoWindow
) {
  const placeId = (document.getElementById("place-id") as HTMLInputElement)
    .value;

  geocoder
    .geocode({ placeId: placeId })
    .then(({ results }) => {
      if (results[0]) {
        map.setZoom(11);
        map.setCenter(results[0].geometry.location);

        const marker = new google.maps.Marker({
          map,
          position: results[0].geometry.location,
        });

        infowindow.setContent(results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;

JavaScript

// Initialize the map.
function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 8,
    center: { lat: 40.72, lng: -73.96 },
  });
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  document.getElementById("submit").addEventListener("click", () => {
    geocodePlaceId(geocoder, map, infowindow);
  });
}

// This function is called when the user clicks the UI button requesting
// a geocode of a place ID.
function geocodePlaceId(geocoder, map, infowindow) {
  const placeId = document.getElementById("place-id").value;

  geocoder
    .geocode({ placeId: placeId })
    .then(({ results }) => {
      if (results[0]) {
        map.setZoom(11);
        map.setCenter(results[0].geometry.location);

        const marker = new google.maps.Marker({
          map,
          position: results[0].geometry.location,
        });

        infowindow.setContent(results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

window.initMap = initMap;
查看範例

測試範例程式碼