Google Maps Geocoding API

此服務也可在 Google Maps JavaScript API 中或透過 Java 與 Python 用戶端程式庫取得。

什麼是地理編碼？

地理編碼是將地址 (例如 "1600 Amphitheatre Parkway, Mountain View, CA") 轉換為地理座標 (例如，緯度 37.423021 與經度 -122.083739) 的程序，您可以用來在地圖上放置標記或定位地圖。

反向地理編碼是將地理座標轉換成人類看得懂之地址的程序。Google Maps Geocoding API 的反向地理編碼服務也可以讓您找到指定地點 ID 的地址。

Google Maps Geocoding API 提供透過 HTTP 要求直接存取這些服務的方式。

在開始之前

本文件的適用對象是，想要在其中一個 Google Maps API 提供的地圖內使用地理編碼資料的網站與行動開發人員。

此服務通常是設計來為靜態 (事先已知) 地址進行地理編碼，以在地圖上放置應用程式內容；此服務在設計上不能即時回應使用者輸入。對於動態地理編碼 (例如，在使用者介面元素內)，請參閱有關 Google Maps JavaScript API 用戶端地理編碼器和/或 Google Play 服務 Location API 的文件。

地理編碼不但是費時且相當耗用資源的工作。請儘可能事先為已知地址進行地理編碼 (使用本文所述的 Google Maps Geocoding API 或其他地理編碼服務)，並將結果儲存在您自己設計的暫存快取中。

您需要 API 金鑰，才能使用 Google Maps Geocoding API。

取得金鑰 使用限制

Google Maps Geocoding API 要求格式

Google Maps Geocoding API 要求必須是下列格式：

https://maps.googleapis.com/maps/api/geocode/output?parameters

其中 output 可以是下列任何一個值：

  • json (建議) 指出以 JavaScript 物件標記法 (JSON) 格式輸出
  • xml 指出以 XML 格式輸出

如果要透過 HTTP 存取 Google Maps Geocoding API，請使用：

http://maps.googleapis.com/maps/api/geocode/output?parameters

針對要求中會包括敏感使用者資料 (例如使用者的位置) 的應用程式，建議不要使用 HTTP。

有些是必要參數，有些則是選擇性參數。根據 URL 標準，參數會使用 & 字元來分隔。

Google Maps API for Work 使用者必須在地理編碼要求中包括有效的 client 與 signature 參數。如需詳細資訊，請參閱 Google Maps API for Work Web 服務。

因為每種要求類型會有不同的可用參數，所以此頁面的其餘部分會分別說明地理編碼與反向地理編碼。

地理編碼 (緯度/經度查詢)

地理編碼要求中的必要參數：

  • address - 您要進行地理編碼的街道地址 (採用所關注國家/地區的郵政服務格式)。應該避免像是商家名稱與單位，套房或樓層號碼等其他地址元素。如需其他指導方針，請參閱常見問題。
         或
    元件 - 您要取得地理編碼的元件篩選器。如需詳細資訊，請參閱元件篩選。如果提供 address，也接受將元件篩選器當成選擇性參數。
  • key - 您應用程式的 API 金鑰。此金鑰會依配額管理目的識別您的應用程式。瞭解如何取得金鑰。

地理編碼要求中的選擇性參數：

  • bounds - 更清楚調整地理編碼結果的檢視點邊界方塊。此參數將只會影響 (但不會完全限制) 地理編碼器產生的結果。(如需詳細資訊，請參閱下方的檢視點偏向)。
  • language - 傳回結果時所使用的語言。請參閱支援的地區語言清單。請注意，我們經常更新支援的語言，因此這份清單可能並不詳盡。如果未提供 language，地理編碼器將會儘可能嘗試使用傳送要求時來源地區的當地語言。
  • region - 地區代碼 (以兩字元值的 ccTLD (頂層地區) 方式指定)。此參數將只會影響 (但不會完全限制) 地理編碼器產生的結果。(如需詳細資訊，請參閱下方的地區偏向)。
  • components - 以直立線符號 (|) 分隔的元件篩選器。每個元件篩選器都包含 component:value 組合，並完全限制地理編碼器產生的結果。如需詳細資訊，請參閱下方的元件篩選。

地理編碼回應

傳回地理編碼回應時，會依照 URL 要求路徑內 output 旗標所指示的格式傳回。

在此範例中，Google Maps Geocoding API 會要求針對 "1600 Amphitheatre Parkway, Mountain View, CA" 查詢傳回 json 回應。

此要求示範如何使用 JSON output 旗標：

https://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY

此要求示範如何使用 XML output 旗標：

https://maps.googleapis.com/maps/api/geocode/xml?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY

按下面的分頁可查看範例 JSON 與 XML 回應。

JSON
{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "1600",
               "short_name" : "1600",
               "types" : [ "street_number" ]
            },
            {
               "long_name" : "Amphitheatre Pkwy",
               "short_name" : "Amphitheatre Pkwy",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Mountain View",
               "short_name" : "Mountain View",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Santa Clara County",
               "short_name" : "Santa Clara County",
               "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" ]
            },
            {
               "long_name" : "94043",
               "short_name" : "94043",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "1600 Amphitheatre Parkway, Mountain View, CA 94043, USA",
         "geometry" : {
            "location" : {
               "lat" : 37.4224764,
               "lng" : -122.0842499
            },
            "location_type" : "ROOFTOP",
            "viewport" : {
               "northeast" : {
                  "lat" : 37.4238253802915,
                  "lng" : -122.0829009197085
               },
               "southwest" : {
                  "lat" : 37.4211274197085,
                  "lng" : -122.0855988802915
               }
            }
         },
         "place_id" : "ChIJ2eUgeAK6j4ARbn5u_wAGqWA",
         "types" : [ "street_address" ]
      }
   ],
   "status" : "OK"
}

請注意，JSON 回應包含兩個根元素：

  • "status" 包含與要求相關的中繼資料。請參閱下方的狀態碼。
  • "results" 包含地理編碼的地址資訊與幾何資訊陣列。

一般而言，地址查詢只會傳回 "results" 陣列中的一個項目，然而如果地址查詢模稜兩可，地理編碼器可能會傳回數個結果。

請注意，如果要擷取這些結果中的值，通常需要「剖析」結果。剖析 JSON 相對容易。如需一些建議的設計模式，請參閱剖析 JSON。

XML
<GeocodeResponse>
 <status>OK</status>
 <result>
  <type>street_address</type>
  <formatted_address>1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA</formatted_address>
  <address_component>
   <long_name>1600</long_name>
   <short_name>1600</short_name>
   <type>street_number</type>
  </address_component>
  <address_component>
   <long_name>Amphitheatre Pkwy</long_name>
   <short_name>Amphitheatre Pkwy</short_name>
   <type>route</type>
  </address_component>
  <address_component>
   <long_name>Mountain View</long_name>
   <short_name>Mountain View</short_name>
   <type>locality</type>
   <type>political</type>
  </address_component>
  <address_component>
   <long_name>San Jose</long_name>
   <short_name>San Jose</short_name>
   <type>administrative_area_level_3</type>
   <type>political</type>
  </address_component>
  <address_component>
   <long_name>Santa Clara</long_name>
   <short_name>Santa Clara</short_name>
   <type>administrative_area_level_2</type>
   <type>political</type>
  </address_component>
  <address_component>
   <long_name>California</long_name>
   <short_name>CA</short_name>
   <type>administrative_area_level_1</type>
   <type>political</type>
  </address_component>
  <address_component>
   <long_name>United States</long_name>
   <short_name>US</short_name>
   <type>country</type>
   <type>political</type>
  </address_component>
  <address_component>
   <long_name>94043</long_name>
   <short_name>94043</short_name>
   <type>postal_code</type>
  </address_component>
  <geometry>
   <location>
    <lat>37.4217550</lat>
    <lng>-122.0846330</lng>
   </location>
   <location_type>ROOFTOP</location_type>
   <viewport>
    <southwest>
     <lat>37.4188514</lat>
     <lng>-122.0874526</lng>
    </southwest>
    <northeast>
     <lat>37.4251466</lat>
     <lng>-122.0811574</lng>
    </northeast>
   </viewport>
  </geometry>
  <place_id>ChIJ2eUgeAK6j4ARbn5u_wAGqWA</place_id>
 </result>
</GeocodeResponse>

請注意，XML 回應是由單一 <GeocodeResponse> 和兩個頂層元素所組成：

  • <status> 包含與要求相關的中繼資料。請參閱下方的狀態碼。
  • 零個或多個 <result> 元素，每個元素都包含單一地理編碼的地址資訊與幾何資訊。

請注意，此回應會比 JSON 回應更長。因此除非您的服務因某種理由而要求使用 xml，否則建議您使用 json 做為偏好的輸出旗標。此外，處理 XML 樹狀結構時必須謹慎小心，如此您才能參照正確的節點和元素。如需一些適用於輸出處理的建議設計模式，請參閱使用 XPath 剖析 XML。

本文件的剩餘部分將會使用 JSON 語法。在大部分情況下，用來在在文件中展示概念或欄位名稱的輸出格式不限。然而，請注意下列的微妙差異：

  • XML 結果會以根 <GeocodeResponse> 元素包裝。
  • JSON 透過複數陣列 (types) 代表具有多個元素的項目，而 XML 使用多個單數元素 (<type>) 代表這些項目。
  • 在 JSON 中是透過空陣列指出空白元素，但在 XML 中會以缺少這類元素的方式指出。例如，未產生任何結果的回應，在 JSON 中將會傳回空的 results 陣列，但在 XML 中不會有 <result> 元素。

狀態碼

地理編碼回應物件內的 "status" 欄位包含要求的狀態，並且可能包含可協助您探究地理編碼無效原因的偵錯資訊。"status" 欄位可能包含下列值：

  • "OK" 指出未發生任何錯誤，已順利剖析地址並且已至少傳回一個地理編碼。
  • "ZERO_RESULTS" 指出地理編碼成功，但是未傳回任何結果。如果傳遞了不存在的 address 給地理編碼器，就可能發生這種情況。
  • "OVER_QUERY_LIMIT" 指出已超出您的配額。
  • "REQUEST_DENIED" 指出您的要求已被拒絕。
  • "INVALID_REQUEST" 通常指出缺少查詢 (address、components 或 latlng)。
  • "UNKNOWN_ERROR" 指出由於發生伺服器錯誤，而無法處理要求。重新嘗試該要求或許會成功。

錯誤訊息

當地理編碼器傳回 OK 以外的狀態碼時，地理編碼回應物件內可能會有額外的 error_message 欄位。此欄位包含有關所提供之狀態碼背後原因的更多詳細資訊。

注意：此欄位不保證一律存在，且其內容可能變更。

結果

當地理編碼器傳回結果時，會將這些結果放在 (JSON) results 陣列內。即使地理編碼器未傳回任何結果 (例如，地址不存在的話)，仍會傳回空的 results 陣列。(XML 回應是由零個或多個 <result> 元素所組成)。

結果一般是由下列欄位組成：

  • types[] 陣列會指出傳回結果的「類型」。此陣列包含零個或多個標籤，指出結果中傳回的特徵類型。例如「芝加哥」的地理編碼會傳回 "locality"，指出「芝加哥」是城市，也會傳回 "political"，指出它是政治實體。

  • formatted_address 是一個字串，包含人類看得懂的此位置地址。此地址通常等於「郵政地址」，有時會因國家/地區而異。(請注意，由於授權限制，有些國家/地區 (例如英國) 不允許散佈實際的郵政地址)。此地址通常是由一或多個「地址元件」所組成。例如，"111 8th Avenue, New York, NY" 包含代表 "111" (門牌號碼、"8th Avenue" (街道)、"New York" (城市) 和 "NY" (美國州別) 的個別地址元件。這些地址元件包含其他資訊，如下所述。

  • address_components[] 是包含個別地址元件 (如上所述) 的陣列。每個 address_component 通常包含：

    • types[] 是指出地址元件之「類型」的陣列。
    • long_name 是地理編碼器所傳回地址元件的完整文字描述或名稱。
    • short_name 是地址元件的縮寫文字型名稱 (如果有的話)。例如，阿拉斯加州的地址元件可能包含 long_name "Alaska"，以及使用 2 個字母郵政縮寫的 short_name "AK"。

    請注意，address_components[] 可以包含比 formatted_address 內所記錄更多的地址元件。

  • postcode_localities[] 是會指明郵遞區號中包含之所有位置的陣列。這只有在結果是包含多個地區的郵遞區號時才會顯示。

  • geometry 包含下列資訊：

    • location 包含完成地理編碼的「latitude,longitude」值。對於標準的地址查詢而言，最重要的就是這個欄位。

    • location_type 儲存有關指定位置的其他資料。目前支援下列值：

      • "ROOFTOP" 指出傳回的結果是我們有精準到街道地址都正確無誤之位置資訊的精確地理編碼。
      • "RANGE_INTERPOLATED" 指出傳回的結果可反映出兩個精準點 (例如交叉路口) 之間以內插計算的近似值 (通常在路上)。當街道地址沒有可用的 rooftop 地理編碼時，通常會傳回內插計算結果。
      • "GEOMETRIC_CENTER" 指出傳回的結果是結果的幾何中心，例如折線 (例如街道) 或多邊形 (例如地區)。
      • "APPROXIMATE" 指出傳回的是近似結果。
    • viewport 包含用於顯示傳回結果的建議檢視點 (指定為兩個「緯度,經度」值，它們定義檢視點邊界方塊的 southwest 與 northeast 角)。一般而言，檢視點是用來框起要向使用者顯示的結果。
    • bounds (選擇性傳回) 儲存可完全包含傳回結果的邊界方塊。請注意，這些邊界可能會和建議的檢視點不符。(例如，舊金山市內嚴格來說包括法拉隆群島，但可能不應該在檢視點中傳回)。

  • partial_match 指出地理編碼器傳回的結果未能完全符合原始要求，但符合一部分要求的地址。您可以檢查原始要求是否有拼寫錯誤和/或不完整的地址。

    最常出現部分相符的情況是，當要求中傳遞的地區內沒有該街道地址存在時。當相同地區中有兩個以上的位置符合要求時，也會傳回部分相符。例如，"21 Henr St, Bristol, UK" 會傳回與 Henry Street 和 Henrietta Street 部分相符。請注意，如果要求包括拼寫錯誤的地址元件，地理編碼服務會建議替代地址。以這種方式觸發的建議也會標示為部分相符。

  • place_id 是可與其他 Google API 搭配使用的唯一識別碼。例如，您可以在 Google Places API 要求中使用 place_id 以取得本地商家的詳細資料，例如電話號碼、營業時間、使用者評論等等。請參閱地點 ID 總覽。

由於不保證 Google Maps Geocoding API 要求的個別回應格式為何，您不應該假設元素會在絕對位置。(尤其是 Geocoding API 回應內的 address_components 數目會根據要求的地址而有不同，並會隨時間而變更)。您應該改為剖析回應並透過運算式選取適當的值。如需詳細資訊，請參閱剖析 Web 服務回應。

地址類型與地址元件類型

結果中的 types[] 陣列會指出「地址類型」。地址類型範例包括街道地址、國家/地區或政治實體。address_components[] 中也有 types[] 陣列，指出地址各部分的類型。範例包括門牌號碼或國家/地區。(以下是完整的類型清單)。地址可以有多個類型。類型可以視為「標籤」。例如，許多城市會被標記為 political 與 locality 類型。

地理編碼器支援並會以地址類型與地址元件類型陣列兩者傳回下列類型：

  • street_address 指出明確的街道地址。
  • route 指出具名路線 (例如 "US 101")。
  • intersection 指出主要交叉路口 (通常是兩條主要道路的交叉)。
  • political 指出政治實體。一般而言，此類型會指出某行政機關的多邊形區域。
  • country 指出國家/地區政治實體，而且這通常是地理編碼器所傳回的最高順序類型。
  • administrative_area_level_1 指出國家/地區層級下的第一順位行政實體。在美國，這些行政層級是州。並非所有國家/地區都有這些行政層級。
  • administrative_area_level_2 指出國家/地區層級下的第二順位行政實體。在美國，這些行政層級是郡。並非所有國家/地區都有這些行政層級。
  • administrative_area_level_3 指出國家/地區層級下的第三順位行政實體。此類型指出次級行政單位。並非所有國家/地區都有這些行政層級。
  • administrative_area_level_4 指出國家/地區層級下的第四順位行政實體。此類型指出次級行政單位。並非所有國家/地區都有這些行政層級。
  • administrative_area_level_5 指出國家/地區層級下的第五順位行政實體。此類型指出次級行政單位。並非所有國家/地區都有這些行政層級。
  • colloquial_area 指出常用的實體替代名稱。
  • locality 指出合併的城市或鄉鎮政治實體。
  • ward 指出特定的日本地區類型，以區分日本地址中的多個地區部分。
  • sublocality 指出地區下的第一順位行政實體。有些位置會收到以下其中一個額外類型：sublocality_level_1 到 sublocality_level_5。每個 sublocality 層級都是一個行政實體。較大的數字表示較小的地理區域。
  • neighborhood 指出具名鄰近地區
  • premise 指出具名位置，通常是有通用名稱的一棟建築物或建築物集合
  • subpremise 指出具名位置下的第一順位實體，通常是有通用名稱的建築物集合內的單一建築物
  • postal_code 指出國家/地區內郵寄地址使用的郵遞區號。
  • natural_feature 指出高知名度的自然特徵。
  • airport 指出機場。
  • park 指出具名公園。
  • point_of_interest 指出具名搜尋點。一般而言，這些 "POI" 都是高知名度的地方實體，不太適合其他類別，例如「帝國大廈」或「自由女神像」。

空的類型清單指出特定地址元件沒有已知類型，例如法國的 Lieu-dit。

除了上述之外，地址元件可能包括下列類型。

注意：此清單可能並不詳盡，且可能變更。

  • floor 指出建築物地址的樓層。
  • establishment 通常指出尚未分類的地點。
  • point_of_interest 指出具名搜尋點。
  • parking 指出停車場或停車設施。
  • post_box 指出特定郵政信箱。
  • postal_town 指出用於某些國家/地區之郵寄地址的地理區域分組，例如 locality 與 sublocality。
  • room 指出建築物地址的房室。
  • street_number 指出明確的門牌號碼。
  • bus_station、train_station 與 transit_station 指出公車、火車或大眾運輸站點的位置。

檢視點偏向

在地理編碼要求中，您可以指示地理編碼服務優先使用指定檢視點 (以邊界方塊表示) 內的結果。您可以透過設定 bounds 參數，在要求 URL 內完成這個動作。請注意，偏向只會「優先使用」邊界內的結果；這些邊界外如果有更相關的結果存在，也會包括在其中。

bounds 參數定義此邊界方塊西南角與東北角的緯度/經度座標 (使用直立線 (|) 字元分隔座標)。

例如，針對 "Winnetka" 進行地理編碼，通常會傳回此芝加哥近郊：

要求：

https://maps.googleapis.com/maps/api/geocode/json?address=Winnetka&key=YOUR_API_KEY

回應：

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Winnetka",
               "short_name" : "Winnetka",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "New Trier",
               "short_name" : "New Trier",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Cook County",
               "short_name" : "Cook County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Illinois",
               "short_name" : "IL",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Winnetka, IL, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 42.1282269,
                  "lng" : -87.7108162
               },
               "southwest" : {
                  "lat" : 42.0886089,
                  "lng" : -87.7708629
               }
            },
            "location" : {
               "lat" : 42.10808340000001,
               "lng" : -87.735895
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 42.1282269,
                  "lng" : -87.7108162
               },
               "southwest" : {
                  "lat" : 42.0886089,
                  "lng" : -87.7708629
               }
            }
         },
         "place_id" : "ChIJW8Va5TnED4gRY91Ng47qy3Q",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

然而，新增 bounds 引數 (可對此地理編碼中的洛杉磯聖費爾南多谷結果定義邊界方塊) 會傳回鄰近該位置稱為 "Winnetka" 的地區。

要求：

https://maps.googleapis.com/maps/api/geocode/json?address=Winnetka&bounds=34.172684,-118.604794|34.236144,-118.500938&key=YOUR_API_KEY

回應：

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Winnetka",
               "short_name" : "Winnetka",
               "types" : [ "neighborhood", "political" ]
            },
            {
               "long_name" : "Los Angeles",
               "short_name" : "LA",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Los Angeles County",
               "short_name" : "Los Angeles County",
               "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" ]
            }
         ],
         "formatted_address" : "Winnetka, Los Angeles, CA, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 34.2355209,
                  "lng" : -118.5534191
               },
               "southwest" : {
                  "lat" : 34.1854649,
                  "lng" : -118.588536
               }
            },
            "location" : {
               "lat" : 34.2048586,
               "lng" : -118.5739621
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 34.2355209,
                  "lng" : -118.5534191
               },
               "southwest" : {
                  "lat" : 34.1854649,
                  "lng" : -118.588536
               }
            }
         },
         "place_id" : "ChIJ0fd4S_KbwoAR2hRDrsr3HmQ",
         "types" : [ "neighborhood", "political" ]
      }
   ],
   "status" : "OK"
}

地區偏向

在地理編碼回應中，Google Maps Geocoding API 傳回的地址結果會受所傳送要求的地區 (通常為國家/地區) 影響。例如，在美國境內搜尋 "San Francisco" 時傳回的結果，會和在西班牙時傳回的結果不同。

您可以設定 Google Maps Geocoding API，使用 region 參數傳回偏向特定地區的結果。此參數可接受指定地區偏向的 ccTLD (國家/地區代碼頂層地區) 引數。大部分 ccTLD 代碼和 ISO 3166-1 代碼完全相同，有些則是明顯例外。例如，英國的 ccTLD 是 "uk" (.co.uk)，但 ISO 3166-1 代碼是 "gb" (嚴格來說是指「大不列顛與北愛爾蘭聯合王國」)。

在已正式推出主要「Google 地圖」應用程式的各個地區，地理編碼結果都可以進行偏向。請注意，偏向只會「優先使用」特定地區內的結果；此地區外如果有更相關的結果存在，也會包括在其中。

例如，"Toledo" 的地理編碼會傳回此結果，因為 Google Maps Geocoding API 的預設地區是設定為美國。要求：

https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&key=YOUR_API_KEY

回應：

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Lucas County",
               "short_name" : "Lucas County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Ohio",
               "short_name" : "OH",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Toledo, OH, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 41.732844,
                  "lng" : -83.4547053
               },
               "southwest" : {
                  "lat" : 41.580266,
                  "lng" : -83.69423700000002
               }
            },
            "location" : {
               "lat" : 41.6639383,
               "lng" : -83.55521200000001
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 41.732844,
                  "lng" : -83.4547053
               },
               "southwest" : {
                  "lat" : 41.580266,
                  "lng" : -83.69423700000002
               }
            }
         },
         "place_id" : "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
         "types" : [ "locality", "political" ]
      },
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Lincoln County",
               "short_name" : "Lincoln County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Oregon",
               "short_name" : "OR",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Toledo, OR, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 44.6383219,
                  "lng" : -123.9129439
               },
               "southwest" : {
                  "lat" : 44.598776,
                  "lng" : -123.954585
               }
            },
            "location" : {
               "lat" : 44.621507,
               "lng" : -123.9384478
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 44.6383219,
                  "lng" : -123.9129439
               },
               "southwest" : {
                  "lat" : 44.598776,
                  "lng" : -123.954585
               }
            }
         },
         "place_id" : "ChIJmcjO1AjUwVQRDsRYrfWvzyo",
         "types" : [ "locality", "political" ]
      },
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Tama County",
               "short_name" : "Tama County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Iowa",
               "short_name" : "IA",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Toledo, IA, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 42.00388600000001,
                  "lng" : -92.56695289999999
               },
               "southwest" : {
                  "lat" : 41.9784431,
                  "lng" : -92.60007299999999
               }
            },
            "location" : {
               "lat" : 41.9972134,
               "lng" : -92.5835266
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 42.00388600000001,
                  "lng" : -92.56695289999999
               },
               "southwest" : {
                  "lat" : 41.9784431,
                  "lng" : -92.60007299999999
               }
            }
         },
         "place_id" : "ChIJvwoVNEOE74cR3oQfIk7m6fU",
         "types" : [ "locality", "political" ]
      },
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Lewis County",
               "short_name" : "Lewis County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Washington",
               "short_name" : "WA",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "98591",
               "short_name" : "98591",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "Toledo, WA 98591, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 46.44799889999999,
                  "lng" : -122.8419249
               },
               "southwest" : {
                  "lat" : 46.43233009999999,
                  "lng" : -122.85575
               }
            },
            "location" : {
               "lat" : 46.4398305,
               "lng" : -122.846783
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 46.44799889999999,
                  "lng" : -122.8419249
               },
               "southwest" : {
                  "lat" : 46.43233009999999,
                  "lng" : -122.85575
               }
            }
         },
         "place_id" : "ChIJPw9m6cb4k1QRyA5L3wI_dRM",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

對於 region=es (西班牙) 的 "Toledo" 地理編碼要求將會傳回西班牙的城市。要求：

https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&region=es&key=YOUR_API_KEY

回應：

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "administrative_area_level_4", "political" ]
            },
            {
               "long_name" : "Vega de Toledo",
               "short_name" : "Vega de Toledo",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Toledo",
               "short_name" : "TO",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Castile-La Mancha",
               "short_name" : "CM",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "Spain",
               "short_name" : "ES",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Toledo, Toledo, Spain",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 39.88605099999999,
                  "lng" : -3.9192423
               },
               "southwest" : {
                  "lat" : 39.8383676,
                  "lng" : -4.0629256
               }
            },
            "location" : {
               "lat" : 39.8628316,
               "lng" : -4.027323099999999
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 39.88605099999999,
                  "lng" : -3.9192423
               },
               "southwest" : {
                  "lat" : 39.8383676,
                  "lng" : -4.0629256
               }
            }
         },
         "place_id" : "ChIJ8f21C60Lag0R_q11auhbf8Y",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

元件篩選

在地理編碼回應中，Google Maps Geocoding API 可以傳回只限特定地區的地址結果。您可以使用 components 篩選器來指定限制。篩選器包含以直立字元 (|) 分隔的 component:value 組合清單。只會傳回符合所有篩選器的結果。篩選器值和其他地理編碼要求一樣，支援相同的拼字校正與部分相符方法。如果地理編碼結果和元件篩選器只有部分相符，回應中將會包含 partial_match 欄位。

可以篩選的 components 包括：

  • route 會比對路線的完整名稱或簡短名稱。
  • locality 會比對 locality 與 sublocality 這兩種類型。
  • administrative_area 會比對所有 administrative_area 層級。
  • postal_code 會比對 postal_code 與 postal_code_prefix。
  • country 會比對國家/地區名稱或兩個字母的 ISO 3166-1 國家/地區代碼。

注意：每個地址元件只能在地址參數或元件篩選器中擇一指定，不能在兩者同時指定。這樣做會造成 ZERO_RESULTS。

具有 components=country:ES 的 "Santa Cruz" 地理編碼將會傳回西班牙加那利群島的 Santa Cruz de Tenerife。要求：

https://maps.googleapis.com/maps/api/geocode/json?address=santa+cruz&components=country:ES&key=YOUR_API_KEY

回應：

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Santa Cruz de Tenerife",
               "short_name" : "Santa Cruz de Tenerife",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Santa Cruz de Tenerife",
               "short_name" : "Santa Cruz de Tenerife",
               "types" : [ "administrative_area_level_4", "political" ]
            },
            {
               "long_name" : "Anaga",
               "short_name" : "Anaga",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Santa Cruz de Tenerife",
               "short_name" : "TF",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Canarias",
               "short_name" : "CN",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "Spain",
               "short_name" : "ES",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Santa Cruz de Tenerife, Santa Cruz de Tenerife, Spain",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 28.487616,
                  "lng" : -16.2356646
               },
               "southwest" : {
                  "lat" : 28.4280248,
                  "lng" : -16.3370045
               }
            },
            "location" : {
               "lat" : 28.4636296,
               "lng" : -16.2518467
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 28.487616,
                  "lng" : -16.2356646
               },
               "southwest" : {
                  "lat" : 28.4280248,
                  "lng" : -16.3370045
               }
            }
         },
         "place_id" : "ChIJcUElzOzMQQwRLuV30nMUEUM",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

包含元件篩選器的查詢將只會傳回與篩選器相符的地理編碼結果。如果找不到相符項目，地理編碼器將會傳回與篩選器本身相符的結果。要求：

https://maps.googleapis.com/maps/api/geocode/json?address=Torun&components=administrative_area:TX|country:US&key=YOUR_API_KEY

回應：

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Texas",
               "short_name" : "TX",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Texas, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 36.5007041,
                  "lng" : -93.5080389
               },
               "southwest" : {
                  "lat" : 25.8371638,
                  "lng" : -106.6456461
               }
            },
            "location" : {
               "lat" : 31.9685988,
               "lng" : -99.9018131
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 36.5015087,
                  "lng" : -93.5080389
               },
               "southwest" : {
                  "lat" : 25.8371638,
                  "lng" : -106.6456461
               }
            }
         },
         "partial_match" : true,
         "place_id" : "ChIJSTKCCzZwQIYRPN4IGI8c6xY",
         "types" : [ "administrative_area_level_1", "political" ]
      }
   ],
   "status" : "OK"
}

只有當您提供會彼此排除的篩選器時，元件篩選才會傳回 ZERO_RESULTS 回應。要求：

https://maps.googleapis.com/maps/api/geocode/json?components=administrative_area:TX|country:FR&key=YOUR_API_KEY

回應：

{
   "results" : [],
   "status" : "ZERO_RESULTS"
}

使用 components 篩選器，可以發出沒有地址參數的查詢，但您無法指定沒有值的元件。要求：

https://maps.googleapis.com/maps/api/geocode/json?components=route:Annegatan|administrative_area:Helsinki|country:Finland&key=YOUR_API_KEY

回應：

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Annegatan",
               "short_name" : "Annegatan",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Helsingfors",
               "short_name" : "Helsingfors",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Finland",
               "short_name" : "FI",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Annegatan, Helsingfors, Finland",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 60.168997,
                  "lng" : 24.9427959
               },
               "southwest" : {
                  "lat" : 60.1626627,
                  "lng" : 24.934
               }
            },
            "location" : {
               "lat" : 60.1657808,
               "lng" : 24.938451
            },
            "location_type" : "GEOMETRIC_CENTER",
            "viewport" : {
               "northeast" : {
                  "lat" : 60.168997,
                  "lng" : 24.9427959
               },
               "southwest" : {
                  "lat" : 60.1626627,
                  "lng" : 24.934
               }
            }
         },
         "place_id" : "ChIJARW7C8sLkkYRgl4je4-RPUM",
         "types" : [ "route" ]
      },
      {
         "address_components" : [
            {
               "long_name" : "Annevägen",
               "short_name" : "Annevägen",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Vanda",
               "short_name" : "Vanda",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Finland",
               "short_name" : "FI",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "01420",
               "short_name" : "01420",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "Annevägen, 01420 Vanda, Finland",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 60.3282738,
                  "lng" : 25.1162163
               },
               "southwest" : {
                  "lat" : 60.32564009999999,
                  "lng" : 25.1076474
               }
            },
            "location" : {
               "lat" : 60.3271069,
               "lng" : 25.1118046
            },
            "location_type" : "GEOMETRIC_CENTER",
            "viewport" : {
               "northeast" : {
                  "lat" : 60.3283059302915,
                  "lng" : 25.1162163
               },
               "southwest" : {
                  "lat" : 60.32560796970849,
                  "lng" : 25.1076474
               }
            }
         },
         "partial_match" : true,
         "place_id" : "ChIJ3UJCNt4GkkYR8-_a8Dh25kA",
         "types" : [ "route" ]
      },
      {
         "address_components" : [
            {
               "long_name" : "Anneplatsen",
               "short_name" : "Anneplatsen",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Helsingfors",
               "short_name" : "Helsingfors",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Finland",
               "short_name" : "FI",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "00100",
               "short_name" : "00100",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "Anneplatsen, 00100 Helsingfors, Finland",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 60.1695664,
                  "lng" : 24.9357125
               },
               "southwest" : {
                  "lat" : 60.168997,
                  "lng" : 24.934
               }
            },
            "location" : {
               "lat" : 60.1692741,
               "lng" : 24.9348016
            },
            "location_type" : "GEOMETRIC_CENTER",
            "viewport" : {
               "northeast" : {
                  "lat" : 60.17063068029151,
                  "lng" : 24.9362052302915
               },
               "southwest" : {
                  "lat" : 60.1679327197085,
                  "lng" : 24.9335072697085
               }
            }
         },
         "partial_match" : true,
         "place_id" : "ChIJeahMqswLkkYR2vQfG1nHI3M",
         "types" : [ "route" ]
      }
   ],
   "status" : "OK"
}

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

「地理編碼」一詞通常是指將人類看得懂的地址轉譯為地圖上的位置。以相反的方式將地圖上的位置轉譯成人類看得懂的地址，這個程序稱為「反向地理編碼」。

必要參數：您必須在反向地理編碼要求中提供下列任一參數，但不得同時提供兩者：

  • latlng - 緯度與經度值 (指定與您要取得人類看得懂的地址最接近的位置)。
  • place_id - 某地點的地點 ID，您要取得該地點人類看得懂的地址。地點 ID 是可與其他 Google API 搭配使用的唯一識別碼。例如，您可以使用 Google Maps Roads API 傳回的 placeID 來取得貼齊點的地址。如需有關地點 ID 的詳細資訊，請參閱地點 ID 總覽。只有要求包括 API 金鑰或 Google Maps API for Work 用戶端 ID 時，才可以指定地點 ID。

反向地理編碼要求中的選擇性參數：

以下是您可以包括在反向地理編碼要求中的選擇性參數：

  • key - 您的應用程式從 Google Developers Console 取得的 API 金鑰。此金鑰會依配額管理目的識別您的應用程式。
  • language - 傳回結果時所使用的語言。請參閱支援的地區語言清單。請注意，我們經常更新支援的語言，因此這份清單可能並不詳盡。如果未提供 language，地理編碼器將會儘可能嘗試使用傳送要求時來源地區的當地語言。
  • result_type - 以直立線符號 (|) 分隔的一或多個地址類型。地址類型範例：country、street_address、postal_code。如需關於允許值的完整清單，請參閱此頁面上的地址類型。指定某類型會限制只傳回該類型的結果。如果指定多個類型，API 將會傳回符合任一類型的所有地址。注意：只有包括 API 金鑰或用戶端 ID 的要求，才能使用此參數。
  • location_type - 以直立線符號 (|) 分隔的一或多個位置類型。指定某類型會限制只傳回該類型的結果。如果指定多個類型，API 將會傳回符合任一類型的所有地址。注意：只有包括 API 金鑰或用戶端 ID 的要求，才能使用此參數。下列是支援的值：
    • "ROOFTOP" 會將結果限制為我們有精準到街道地址都正確無誤之位置資訊的地址。
    • "RANGE_INTERPOLATED" 限制只傳回能反映兩個精準點 (例如交叉路口) 之間以內插計算出近似值 (通常在路上) 的那些結果。內插計算範圍通常指出街道地址沒有可用的 rooftop 地理編碼。
    • "GEOMETRIC_CENTER" 限制結果只能傳回位置的幾何中心，例如折線 (例如街道) 或多邊形 (例如地區)。
    • "APPROXIMATE" 限制只能傳回那些描述為近似值的結果。

如果 result_type 與 location_type 限制同時存在，那麼 API 將只會傳回同時符合 result_type 與 location_type 限制的那些結果。

緯度/經度的反向地理編碼

下列查詢包含布魯克林某位置的緯度/經度值：

https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452&key=YOUR_API_KEY

注意：以 latlng 參數傳遞時，請確定緯度與經度值之間沒有空格存在。

上述查詢會傳回下列結果：

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "277",
               "short_name" : "277",
               "types" : [ "street_number" ]
            },
            {
               "long_name" : "Bedford Avenue",
               "short_name" : "Bedford Ave",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Williamsburg",
               "short_name" : "Williamsburg",
               "types" : [ "neighborhood", "political" ]
            },
            {
               "long_name" : "Brooklyn",
               "short_name" : "Brooklyn",
               "types" : [ "sublocality", "political" ]
            },
            {
               "long_name" : "Kings",
               "short_name" : "Kings",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "New York",
               "short_name" : "NY",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "11211",
               "short_name" : "11211",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "277 Bedford Avenue, Brooklyn, NY 11211, USA",
         "geometry" : {
            "location" : {
               "lat" : 40.714232,
               "lng" : -73.9612889
            },
            "location_type" : "ROOFTOP",
            "viewport" : {
               "northeast" : {
                  "lat" : 40.7155809802915,
                  "lng" : -73.9599399197085
               },
               "southwest" : {
                  "lat" : 40.7128830197085,
                  "lng" : -73.96263788029151
               }
            }
         },
         "place_id" : "ChIJd8BlQ2BZwokRAFUEcm_qrcA",
         "types" : [ "street_address" ]
      },

  ... Additional results[] ...

請注意，反向地理編碼器會傳回多個結果。"formatted_address" 結果不只是郵政地址，而是依地理位置命名的任何方式。例如，為芝加哥市內的某點進行地理編碼時，地理編碼的那點可以代表街道地址、城市 (芝加哥)、州 (伊利諾伊州) 或國家/地區 (美國)。對地理編碼器而言，它們全都是「地址」。反向地理編碼器會將這些類型傳回為有效結果。

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

先前查詢所傳回 formatted_address 值的完整清單如下所示。

"formatted_address" : "277 Bedford Avenue, Brooklyn, NY 11211, USA",
"formatted_address" : "Grand St/Bedford Av, Brooklyn, NY 11211, USA",
"formatted_address" : "Grand St/Bedford Av, Brooklyn, NY 11249, USA",
"formatted_address" : "Bedford Av/Grand St, Brooklyn, NY 11211, USA",
"formatted_address" : "Brooklyn, NY 11211, USA",
"formatted_address" : "Williamsburg, Brooklyn, NY, USA",
"formatted_address" : "Brooklyn, NY, USA",
"formatted_address" : "New York, NY, USA",
"formatted_address" : "New York, USA",
"formatted_address" : "United States",

一般而言，會從最特定到最不特定的地址傳回，較確切的地址就是最重要的結果，如本例中所示。請注意，我們會從最特定的街道地址到最不特定的政治實體傳回不同的地址類型，例如鄰近地區、城市、郡、州/省等等。如果要比對特定地址類型，請參閱下方的根據類型限制結果一節。

注意：反向地理編碼是一個預估值。地理編碼器會嘗試在特定容許範圍內找到最接近的可定址位置。如果找不到相符項目，地理編碼器將會傳回零個結果。

地點 ID 的反向地理編碼

下列查詢包含布魯克林某地點的地點 ID：

https://maps.googleapis.com/maps/api/geocode/json?place_id=ChIJd8BlQ2BZwokRAFUEcm_qrcA&key=YOUR_API_KEY

上述查詢會傳回下列結果：

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "277",
               "short_name" : "277",
               "types" : [ "street_number" ]
            },
            {
               "long_name" : "Bedford Ave",
               "short_name" : "Bedford Ave",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Williamsburg",
               "short_name" : "Williamsburg",
               "types" : [ "neighborhood", "political" ]
            },
            {
               "long_name" : "Brooklyn",
               "short_name" : "Brooklyn",
               "types" : [ "sublocality_level_1", "sublocality", "political" ]
            },
            {
               "long_name" : "Kings County",
               "short_name" : "Kings County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "New York",
               "short_name" : "NY",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "11211",
               "short_name" : "11211",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "277 Bedford Ave, Brooklyn, NY 11211, USA",
         "geometry" : {
            "location" : {
               "lat" : 40.714232,
               "lng" : -73.9612889
            },
            "location_type" : "ROOFTOP",
            "viewport" : {
               "northeast" : {
                  "lat" : 40.7155809802915,
                  "lng" : -73.9599399197085
               },
               "southwest" : {
                  "lat" : 40.7128830197085,
                  "lng" : -73.96263788029151
               }
            }
         },
         "partial_match" : true,
         "place_id" : "ChIJd8BlQ2BZwokRAFUEcm_qrcA",
         "types" : [ "street_address" ]
      }
   ],
   "status" : "OK"
}

根據類型限制反向地理編碼

下列範例會限制只傳回那些具有 ROOFTOP 位置類型與 street_address 地址類型的地址。

https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452&location_type=ROOFTOP&result_type=street_address&key=YOUR_API_KEY

注意：這些限制只適用於反向地理編碼。

反向地理編碼回應

反向地理編碼回應的格式與地理編碼回應的格式相同。請參閱地理編碼回應。以下是反向地理編碼回應中可見的狀態碼。

反向地理編碼狀態碼

地理編碼回應物件內的 "status" 欄位包含要求的狀態，並且可能包含可協助您探究反向地理編碼無效原因的偵錯資訊。"status" 欄位可能包含下列值：

  • "OK" 指出未發生任何錯誤，並且已至少傳回一個地址。
  • "ZERO_RESULTS" 指出反向地理編碼成功，但是未傳回任何結果。如果傳遞了遠端位置中的 latlng 給地理編碼器，就可能發生這種情況。
  • "OVER_QUERY_LIMIT" 指出已超出您的配額。
  • "REQUEST_DENIED" 指出要求已被拒絕。原因是要求包括 result_type 或 location_type 參數，但未包括 API 金鑰或用戶端 ID。
  • "INVALID_REQUEST" 一般指出下列其中一種情況：
    • 缺少查詢 (address、components 或 latlng)。
    • 指定的 result_type 或 location_type 無效。
  • "UNKNOWN_ERROR" 指出由於發生伺服器錯誤，而無法處理要求。重新嘗試該要求或許會成功。

sensor 參數

Google Maps API 先前要求您包括 sensor 參數，以指出您的應用程式是否使用感應器來判斷使用者的位置。現在已不再需要此參數。

傳送您對下列選項的寶貴意見...

這個網頁
文件意見
Google Maps Geocoding API
Google Maps Geocoding API
產品意見
需要協助嗎？請前往我們的支援網頁。