地理編碼服務

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

總覽

「地理編碼」是指將地址 (例如 "1600 Amphitheatre Parkway, Mountain View, CA) 轉換為地理座標 (例如緯度 37.423021 和經度 -122.083739) 的程序,而您可以使用這些座標來放置標記或定位地圖。

反向地理編碼是將地理座標轉換為使用者可理解的地址的程序 (請參閱反向地理編碼 (地址查詢))。

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

Maps JavaScript API 提供 Geocoding 類別,用於在使用者輸入內容進行地理編碼及反向地理編碼。如果想為已知的靜態地址進行地理編碼,請參閱地理編碼網路服務

開始

使用 Maps JavaScript API 的 Geocoding 服務前,請先確認您已在 Maps JavaScript API 中設定該專案的 Geocoding API。

查看已啟用的 API 清單:

  1. 前往 Google Cloud Console
  2. 按一下「選取專案」按鈕,然後選取您為 Maps JavaScript API 設定的專案,然後按一下「開啟」
  3. 資訊主頁的 API 清單中,尋找 Geocoding API
  4. 如果清單中有這個 API,表示您已完成所有設定。如果 API 未列出 API,請啟用該 API:
    1. 選取頁面頂端的「ENABLE API」,即可顯示「Library」(資料庫) 分頁標籤。或者,從左側選單中選取 [程式庫]
    2. 搜尋 Geocoding API,然後從結果清單中選取該 API。
    3. 選取「啟用」。程序完成之後,Geocoding API 就會顯示在資訊主頁的 API 清單中。

價格與政策

定價

新的即付即用定價方案已於 2018 年 7 月 16 日生效,適用於地圖介面集、路徑介面集和地點介面集。如要進一步瞭解 JavaScript Geocoding 服務的全新定價和用量限制,請參閱 Geocoding API 的用量和帳單

頻率限制

請留意其他要求的頻率限制:

無論有多少專案共用同一個專案,每個使用者工作階段都會套用額外的頻率限制。首次載入 API 時,系統會分配初始要求的配額。這個配額用盡後,API 則會每秒對額外的要求執行頻率限制。如果在特定時間範圍內發出太多要求,API 會傳回 OVER_QUERY_LIMIT 回應代碼。

個別工作階段頻率限制可避免使用用戶端服務進行批次要求,例如批次地理編碼。如為批次要求,請使用 Geocoding API 網路服務

政策

使用 Geocoding 服務時,必須遵守 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 參數只會影響到地理編碼器的結果,但不會完全限制。詳情請參閱下方的區域代碼偏誤一節。

地理編碼回應

地理編碼服務需要擷取回呼方法,才能在擷取 Geocodingr' 結果時執行。這個回呼應傳遞兩個參數,依序保存 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[] 是一個陣列,用來傳回傳回結果的地址類型。這個陣列包含一組零或多個標記,用於識別結果中傳回的特徵類型。舉例來說,「{9}芝加哥」的地理編碼會傳回「quot;locality&quot」;這個欄位代表「芝加哥」,也是傳回「政治」的「政治」內容。如要進一步瞭解地址類型和地址元件類型,請參閱下文。
  • formatted_address 是包含這個位置使用者可理解地址的字串。

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

    格式化的地址在邏輯上是由一或多個位址元件組成。舉例來說,地址為「111 8th Avenue, New York, NY」是由以下元件組成:「com111」(街道號碼)、「8th Avenue」(路線)、「New York」(紐約) 和「NY」(美國州) 等地址。)

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

  • address_components[] 是一個陣列,其中包含適用於此地址的個別元件。

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

    • types[] 是一個陣列,指出地址元件的「類型」。請參閱支援的類型清單。
    • long_name 是 Geocoding 傳回的地址元件的完整文字說明或名稱。
    • short_name 是地址元件的縮寫文字名稱 (如果有的話)。舉例來說,阿拉斯加州的地址元件可能會包含「阿拉斯加」的 long_name,以及「AK」的 short_name;請使用 2 個字母的郵遞區號縮寫。

    請注意,以下有關 address_components[] 陣列的事實:

    • 地址元件的陣列可包含比 formatted_address 更多的元件。
    • 除了 formatted_address 中的實體以外,這個陣列不一定會包含含有地址的所有政治實體。如要擷取包含特定地址的所有政治實體,您應使用反向地理編碼,將地址的經緯度做為參數傳遞至要求。
    • 但不保證會讓要求的格式保持不變。具體來說,address_components 的數量會因要求的位址而異,且同一個地址可能會隨時間改變。元件可以變更陣列中的位置。元件類型可以變更。後續回覆中可能會缺少特定元件。

    如要進一步瞭解地址類型和地址元件類型,請參閱下文。

  • partial_match 表示地理編碼器無法傳回原始要求中的完全比對,但可以比對出部分要求的位址。建議您檢查原始要求的錯字,和/或不完整的地址。

    部分比對結果通常出於街道地址不存在於您於要求中傳送的縣市內。如果要求比對同一個區域內的兩個或更多地點,系統也可能會傳回部分相符項目。例如,「quoll;Hillpar St, Bristol, UK」將傳回 Henry Street 和 Henrietta Street 的部分相符結果。請注意,如果要求含有遺漏的地址元件,地理編碼服務可能會提供替代地址。以這種方式觸發的建議也會標示為部分比對。

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

    • location 包含地理編碼的經緯度值。請注意,我們會將這個位置以 LatLng 物件傳回,而非格式化字串。
    • location_type 會儲存指定位置的其他資料。目前支援下列值:
      • ROOFTOP 表示傳回的結果反映的是精確的地理編碼。
      • RANGE_INTERPOLATED 表示傳回的結果反映了兩個點 (例如交集) 之間插入的近似值 (通常在道路上)。一般而言,當街道地址無法使用屋頂地理編碼時,通常會傳回內插結果。
      • GEOMETRIC_CENTER 表示傳回的結果是結果的幾何圖形中心,例如折線 (例如街道) 或多邊形 (區域)。
      • APPROXIMATE 表示傳回的結果為約略值。

    • viewport 會儲存所傳回結果的建議可視區域。
    • bounds (選用傳回) 會儲存可完全傳回傳回結果的 LatLngBounds。請注意,這些邊界可能會不同於所建議的檢視點 (舉例來說,舊金山是法拉倫群島,在技術層面上是城市的一部分,但不應在可視區域中傳回)。

地理編碼會由瀏覽器透過瀏覽器偏好的語言設定或使用 language 參數載入 API JavaScript 時所指定的語言傳回。(詳情請參閱本地化的相關說明)。

地址類型和地址元件類型

GeocodingResult 中的 types[] 陣列指出地址類型。您也可以在 GeocodingAddressComponent 中傳回 types[] 陣列,指出特定地址元件的類型。地理編碼器傳回的地址可能會有多種類型,這些類型都可能視為標記。舉例來說,許多城市都會加上 politicallocality 類型標記。

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

  • street_address 表示精確的街道地址。
  • route 表示具名路線 (例如「US 101」)。
  • intersection 代表主要的十字路口,通常是兩條主要道路。
  • political 代表政治實體。通常,這個類型代表某些民間組織的多邊形。
  • country 表示國家政治實體,通常是 Geocoding 傳回的最高訂單類型。
  • administrative_area_level_1 表示國家/地區層級以下的第一位公民實體。在美國,這類行政層級是州/省。並非所有國家/地區都設有這些行政區。在大多數情況下,行政區名稱/行政區名稱是 ISO 3166-2 子群組和其他廣泛流通的清單,會與 BigQuery 的
  • 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 參數定義了洛杉磯聖費南多谷的定界框,這類地理編碼就會傳回該位置名為「quonet;Winnetka&quot」的街區:

{
  "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 (「頂層網域」) 並對應到兩個字元值,例如「quot;co.uk」。在某些情況下,region 標記也支援 ISO-3166-1 代碼,這些代碼有時會與 ccTLD 值不同 (例如「GB」代表「英國」)。

使用 region 參數時:

  • 您只能指定一個國家/地區。系統會忽略多個值,而且可能會導致要求失敗。
  • 只能使用兩個字元的區域子標記 (萬國碼 (Unicode) CLDR 格式)。所有其他輸入內容都會造成錯誤。
  • 系統僅支援 Google 地圖平台涵蓋範圍詳細資料中所列的國家/地區。

凡是主要 Google 地圖應用程式提供地理編碼的每個網域,都可以傳送地理編碼要求。請注意,偏誤只會「偏好」特定網域的結果;如果網域外還有其他相關結果,可能會納入這些結果。

舉例來說,如果「地理編碼服務」的預設網域設為美國,請傳回「quole;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"
}

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

{
  "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"
}

元件篩選

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

地理編碼器只會傳回符合所有元件篩選器的結果。也就是說,系統會將篩選器規格視為 AND,而不是 OR。

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

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

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

「地理編碼」一詞通常是指將使用者可理解的地址轉譯為地圖上的位置。反之,將地圖上某個位置轉譯為使用者可理解的地址,就是所謂的反向地理編碼

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

以下範例會將緯度/經度值進行地理編碼,並將地圖置於該位置的中心,藉此顯示包含格式化地址的資訊視窗:

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

查看範例