地理編碼服務

總覽

地理編碼是指將地址 (例如 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 的地址。

自選參數：

  • bounds：LatLngBounds，您可在此範圍內進一步調整地理編碼結果。bounds 參數只會影響但不會完全限制地理編碼器提供的結果。詳情請參閱下方「可視區域自訂調整」一節。
  • componentRestrictions：用於將結果限制在特定區域。詳情請參閱下方「元件篩選」一節。
  • region：區碼，指定為雙字元 (非數字) 萬國碼 (Unicode) 區域子標記。在大多數情況下，這些標記會直接對應到熟悉的 ccTLD (「頂層網域」) 雙字元值。region 參數只會影響但不會完全限制地理編碼器提供的結果。詳情請參閱下方「區碼自訂調整」一節。
  • extraComputations：這個參數唯一允許的值為 ADDRESS_DESCRIPTORS。詳情請參閱 地址描述符。
  • fulfillOnZeroResults：在回應中以 ZERO_RESULT 狀態履行承諾。這是因為即使地理編碼結果為零，仍可能會傳回其他回應層級欄位。詳情請參閱「 Fulfill on Zero Results」。

地理編碼回應

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

地理編碼結果

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[] 陣列，表示特定位址元件的類型。地理編碼器傳回的地址可能包含多種類型，這些類型可視為標記。舉例來說，許多城市都會加上 political 和 locality 類型標記。

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

  • 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_1 到 sublocality_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 表示地理區域分組 (例如 locality 和 sublocality)，在部分國家/地區用於郵寄地址。
  • room 表示建築物地址的房號。
  • street_number 表示精確的門牌號碼。
  • bus_station、train_station 和 transit_station 表示公車、火車或大眾運輸停靠站的位置。

狀態碼

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

  • "OK" 表示沒有發生任何錯誤。地址剖析成功，且系統傳回至少一組地理編碼。
  • "ZERO_RESULTS" 表示地理編碼成功，但沒有傳回任何結果。如果地理編碼器收到不存在的 address，就有可能發生這種情況。
  • "OVER_QUERY_LIMIT" 表示您已超過配額。
  • "REQUEST_DENIED" 表示您的要求遭拒。這個網頁禁止使用地理編碼器。
  • "INVALID_REQUEST" 通常表示缺少查詢內容 (address、components 或 latlng)。
  • "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 參數，依 country 和 postalCode 進行篩選：

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);
  }
});
}

在無結果時提供回應

對於反向地理編碼，根據預設，承諾會在 status=ZERO_RESULTS 上中斷。不過，在這種情況下，系統仍可能會填入 plus_code 和 address_descriptor 的額外回應層級欄位。如果為 fulfillOnZeroResults 參數提供 true，則不會中斷承諾，且如果有這些額外欄位，則可透過承諾存取這些欄位。

以下是南極洲經緯度的這項行為示例。即使沒有反向地理編碼結果，如果設定 fulfillOnZeroResults=true，我們還是可以在承諾中顯示 Plus Code。

    function addressDescriptorReverseGeocoding() {
      var latlng = new google.maps.LatLng(-75.290330, 38.653861);
      geocoder
        .geocode({
          'location': latlng,
          'fulfillOnZeroResults': true,
        })
        .then((response) => {
          console.log(response.plus_code);
        })
        .catch((error) => {
          window.alert(`Error`);
        });
    }

地址描述元

地址描述符包含其他資訊，可用於描述地點的標誌和區域。請參閱地址描述符示範影片，瞭解這項功能。

您可以使用 extraComputations 參數啟用地址描述符。在地理編碼要求、反向地理編碼要求或地點地理編碼要求中加入 extra_computations=ADDRESS_DESCRIPTORS，即可在回應中接收地址描述符。

地點地理編碼範例

以下查詢包含位於德里的地點地址。

function addressDescriptorPlaceIdLookup() {
  geocoder.geocode({ 
    'placeId': 'ChIJyxAX8Bj9DDkRgBfAnBYa66Q',
    'extraComputations': ['ADDRESS_DESCRIPTORS']
    }, function(results, status) {
    if (status == 'OK') {
      console.log(results[0].address_descriptor);
    } else {
      window.alert('Geocode was not successful for the following reason: ' + status);
    }
  });
}

反向地理編碼範例

以下查詢包含德里某個地點的緯度/經度值。

    function addressDescriptorReverseGeocoding() {
      var latlng = new google.maps.LatLng(28.640964,77.235875);
      geocoder
        .geocode({
          'location': latlng,
          'extraComputations': ["ADDRESS_DESCRIPTORS"],
        })
        .then((response) => {
          console.log(response.address_descriptor);
        })
        .catch((error) => {
          window.alert(`Error`);
        });
    }

地址描述元範例

address_descriptor 的範例如下所示。

  {
    "address_descriptor" : {
       "areas" : [
          {
             "containment" : "OUTSKIRTS",
             "display_name" : {
                "language_code" : "en",
                "text" : "Turkman Gate"
             },
             "place_id" : "ChIJ_7LLvyb9DDkRMKKxP9YyXgs"
          },
          {
             "containment" : "OUTSKIRTS",
             "display_name" : {
                "language_code" : "en",
                "text" : "Chandni Chowk"
             },
             "place_id" : "ChIJWcXciBr9DDkRUb4dCDykTwI"
          },
          {
             "containment" : "NEAR",
             "display_name" : {
                "language_code" : "en",
                "text" : "Katar Ganj"
             },
             "place_id" : "ChIJH3cWUyH9DDkRaw-9CjvcRvY"
          }
       ],
       "landmarks" : [
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "Delite Cinema"
             },
             "straight_line_distance_meters" : 29.9306755065918,
             "place_id" : "ChIJLfiYDCT9DDkROoEa7NdupUM",
             "travel_distance_meters" : 418.7794799804688,
             "spatial_relationship" : "ACROSS_THE_ROAD",
             "types" : [ "establishment", "movie_theater", "point_of_interest" ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "YES Bank"
             },
             "straight_line_distance_meters" : 66.83731079101562,
             "place_id" : "ChIJFYHM3yb9DDkRRKGkZl2mpSQ",
             "travel_distance_meters" : 489.0340270996094,
             "spatial_relationship" : "DOWN_THE_ROAD",
             "types" : [ "bank", "establishment", "finance", "point_of_interest" ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "UCO Bank"
             },
             "straight_line_distance_meters" : 25.38849639892578,
             "place_id" : "ChIJ-c6_wCb9DDkRjIk1LeqRtGM",
             "travel_distance_meters" : 403.2246398925781,
             "spatial_relationship" : "ACROSS_THE_ROAD",
             "types" : [ "atm", "bank", "establishment", "finance", "point_of_interest" ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "Delhi By Cycle Meeting Point"
             },
             "straight_line_distance_meters" : 44.02867126464844,
             "place_id" : "ChIJNxVfkSb9DDkRJD22l-eGFdM",
             "travel_distance_meters" : 97.41281890869141,
             "spatial_relationship" : "AROUND_THE_CORNER",
             "types" : [
                "establishment",
                "point_of_interest",
                "tourist_attraction",
                "travel_agency"
             ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "Axis Bank Branch"
             },
             "straight_line_distance_meters" : 102.3495178222656,
             "place_id" : "ChIJr3uaDCT9DDkR8roHTVSn1x4",
             "travel_distance_meters" : 330.8566284179688,
             "spatial_relationship" : "DOWN_THE_ROAD",
             "types" : [ "bank", "establishment", "finance", "point_of_interest" ]
          }
       ]
    }
  }

每個 address_descriptor 物件都包含兩個陣列：landmarks 和 areas。landmarks 陣列最多包含 5 個結果，並依關聯性排序，考量與要求座標的距離、地標的普遍性和可見度。每個地標結果都包含下列值：

  • place_id 是地標結果的地點 ID。請參閱地點 ID 總覽。
  • display_name 是地標的顯示名稱，包含 language_code 和 text。
  • straight_line_distance_meters 是輸入座標和地標結果之間的點對點距離，以公尺為單位。
  • travel_distance_meters 是輸入座標和地標結果之間，透過道路網路 (忽略道路限制) 所經過的距離 (以公尺為單位)。
  • spatial_relationship 是輸入座標與地標結果之間的預估關係：
    • 在下列情況皆不適用時，預設關係為 "NEAR"。
    • "WITHIN" 當輸入座標位於與地標相關聯的結構體邊界內時。
    • "BESIDE" 當輸入座標與地標或地標的存取點直接相鄰時。
    • "ACROSS_THE_ROAD" 當輸入座標與路線另一側的地標正好相反。
    • "DOWN_THE_ROAD"：輸入座標與地標位於同一路線，但不是 "BESIDES" 或 "ACROSS_THE_ROAD"。
    • "AROUND_THE_CORNER"：當輸入座標沿著與地標垂直的路線 (僅限單轉彎)。
    • "BEHIND" 當輸入座標在空間上接近地標，但距離其存取點較遠時。
  • types 是地標的地點類型。

areas 物件最多包含 3 個回覆，且只限於代表小區域的地點，例如鄰里、次區域和大型建築群。系統會先列出包含要求座標的區域，並依大小排序。每個 areas 結果都包含下列值：

  • place_id 是區域結果的地點 ID。請參閱地點 ID 總覽。
  • display_name 是區域的顯示名稱，包含 language_code 和 text。
  • containment 是輸入座標與區域結果之間的預估包含關係：
    • 在下列情況皆不適用時，預設關係為 "NEAR"。
    • "WITHIN" 當輸入的座標接近區域中心時。
    • "OUTSKIRTS" 當輸入座標接近區域邊緣時。

地址描述元涵蓋範圍

這項功能僅適用於特定國家/地區。

這是預先發布版功能，歡迎提供意見。請傳送電子郵件至 address-descriptors-feedback@google.com。

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

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

請在 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;
index.ts

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;
index.js
查看範例

測試範例程式碼

請注意，在前一個範例中，我們選取 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;
index.ts

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;
index.js
查看範例

測試範例程式碼