Maps API 網路服務

Google Geocoding API

  1. 什麼是地理編碼?
  2. 目標讀者
  3. 使用限制
  4. 地理編碼要求
  5. 地理編碼回應
    1. JSON 輸出格式
    2. XML 輸出格式
    3. 狀態碼
    4. 結果
    5. 地址元件類型
  6. 反向地理編碼
  7. 檢視區自訂調整
  8. 區域自訂調整
  9. 元件篩選

本文件將探討最新版的 Geocoding API (第 3 版)。請注意,舊版的 Geocoding API 第 2 版已不適用。該服務的使用者必須升級至此版本。

想在 JavaScript 應用程式中使用這個服務?請試試看 Google Maps API 第 3 版的 Geocoder 類別。

什麼是地理編碼?

地理編碼是指將地址 (例如 1600 Amphitheatre Parkway, Mountain View, CA) 轉換成地理座標 (例如緯度 37.423021 和經度 -122.083739) 的程序,而您可以使用這些座標來放置標記或設定地圖位置。Google Geocoding API 可讓使用者直接透過 HTTP 要求存取 Geocoder。另外,此服務能讓您執行反向作業 (將座標轉換為位址);此程序也就是「反向地理編碼」。

目標讀者

本文件的目標讀者是網站和 Google 行動服務的開發人員,讓他們能夠在某個 Google Maps API 所提供的地圖中使用地理編碼資料。文中內容則涵蓋了 API 使用簡介以及可用參數的參考資料。

這項服務的設計通常是用來計算靜態 (事先已知) 地址的地理編碼,以便在地圖上放置應用程式內容,而「不是」用來即時回應如使用者輸入等作業。如需動態的地理編碼資訊 (例如在使用者介面元素之內),請參閱 JavaScript API 第 2 版 Client Geocoder JavaScript API 第 3 版 Client GeocoderMaps API for Flash Client Geocoder 的說明文件。

地理編碼這項工作不僅費時且需要耗用大量資源。如果可能,請預先為已知的地址進行地理編碼 (使用此處描述的 Geocoding API 或其他地理編碼服務),並將結果儲存在您個人設計的暫存快取中。

使用限制

Google Geocoding API 有查詢限制,每天只能發出 2,500 個地理位置要求 (Google Maps API for Business 使用者每天最多可執行 100,000 個要求)。要實施這項限制的原因,是避免有人濫用 Geocoding API 以及/或將其用在其他目的。此限制日後如有變更,恕不另行通知。此外,我們也限制要求頻率,以避免發生濫用服務的狀況。如果您已超過 24 小時的使用上限或是濫用服務,Geocoding API 將暫時無法運作。如果您持續超過上限,則會遭到封鎖,無法使用 Geocoding API。

注意:Geocoding API 只能搭配 Google 地圖一起使用;如未在地圖上顯示結果,即無法使用地理編碼產生結果。如要查看使用限制的完整資訊,請參閱《Maps API 服務條款》的授權限制

地理編碼要求

Geocoding API 要求必須採用以下格式:

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

其中,output 可為下列任一個值︰

  • json (建議使用) 表示輸出格式為 JavaScript 物件註解 (JSON)
  • xml 表示輸出格式為 XML

如要透過 HTTPS 存取 Geocoding API,請使用:

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

應用程式如果在要求中包含機密使用者資料 (如使用者位置),建議使用 HTTPS。

無論何種情況,有些參數為必要,而有些參數則為選用。跟網址的標準一樣,這裡的所有參數都會以 & 字元分隔。參數清單和其可能的值列舉如下。

必要參數

  • address:您要進行地理編碼的地址。
        
    latlng:您將為此文字經/緯度值取得最接近的人類可讀地址。詳情請見反向地理編碼
        
    components:您想為其取得地理編碼的元件篩選器。詳請請見元件篩選。如果您提供了 address,系統也可以接受元件篩選器做為選用參數。
  • sensor:指出地理編碼要求的來源裝置是否附有位置感應器。這個值必須是 truefalse

Maps API for Business 使用者必須在地理編碼要求中加上有效的 clientsignature 參數。詳情請見 Maps API for Business 網路服務

選用參數

  • bounds:您可在此檢視區的邊框中,進一步自訂調整地理編碼結果。這個參數會影響但不會完全限制 Geocoder 的結果 (詳情請參閱下方的檢視區自訂調整)。
  • language:傳回結果所要使用的語言。請參閱支援的網域語言清單。請注意,我們經常更新支援的語言,因此這份清單可能會有遺漏。如果未提供 language,Geocoder 會嘗試使用要求傳送所在網域 (不管位於何處) 的當地語言。
  • region:將區域代碼指定為 ccTLD (「頂層網域」) 的兩位字元值。這個參數會影響但不會完全限制 Geocoder 的結果 (詳情請參閱下方的區域自訂調整)。
  • components:元件篩選器,以直立線 (|) 分隔。每個元件篩選器都由一對 component:value 組成,並且將完全限制 Geocoder 的結果。詳情請參閱下方的元件篩選

地理編碼回應

地理編碼回應的傳回格式會在網址要求的路徑內以 output 旗標標示。

JSON 輸出格式

在這個範例中,Geocoding API 會針對「1600 Amphitheatre Parkway, Mountain View, CA」的查詢要求 json 格式的回應:

http://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&sensor=true_or_false

在這個範例中,我們故意使用變數 true_or_false 來表示 sensor 參數,藉此提醒您「必須」明確地將這個值設為 truefalse

此要求傳回的 JSON 顯示如下。請注意,實際 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",
               "short_name" : "Santa Clara",
               "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 Pkwy, Mountain View, CA 94043, USA",
         "geometry" : {
            "location" : {
               "lat" : 37.42291810,
               "lng" : -122.08542120
            },
            "location_type" : "ROOFTOP",
            "viewport" : {
               "northeast" : {
                  "lat" : 37.42426708029149,
                  "lng" : -122.0840722197085
               },
               "southwest" : {
                  "lat" : 37.42156911970850,
                  "lng" : -122.0867701802915
               }
            }
         },
         "types" : [ "street_address" ]
      }
   ],
   "status" : "OK"
}

請注意,JSON 回應包含兩個根元素:

  • "status" 包含要求的中繼資料,請參閱下方的狀態碼
  • "results" 包含一個地理編碼地址資訊和幾何圖形資訊的陣列。

通常,進行地址查閱時只會傳回 "results" 陣列中的一個項目,不過如果輸入的地址查詢不明確,Geocoder 就可能會傳回多個結果。

注意,這些結果通常都必須經過「剖析」,才能讓您從結果中擷取值。剖析 JSON 非常容易。請參閱剖析 JSON,瞭解部分建議的設計模式。

XML 輸出格式

在這個範例中,Geocoding API 會針對上述的同一個「1600 Amphitheatre Parkway, Mountain View, CA」查詢要求 xml 格式的回應︰

http://maps.googleapis.com/maps/api/geocode/xml?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&sensor=true_or_false

此要求傳回的 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>
 </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 或遠端位置的 latlng,就有可能發生這種情況。
  • "OVER_QUERY_LIMIT" 表示您超過配額了。
  • "REQUEST_DENIED" 表示您的要求已遭拒絕,通常是因為缺少 sensor 參數。
  • "INVALID_REQUEST" 一般表示查詢 (addresslatlng) 遺失了。

結果

Geocoder 傳回的結果會放置在 (JSON) results 陣列中。即使 Geocoder 未傳回任何結果 (例如地址不存在時),它還是會傳回一個空的 results 陣列 (XML 回應由零個或多個 <result> 元素組成)。

一般結果中會包含下列欄位:

  • types[] 陣列指出傳回結果的「類型」。這個陣列包含一或多個標記的組合,這些標記用於識別結果中傳回的地圖項類型。例如,「Chicago」的地理編碼會傳回「locality」,表示「Chicago」是一個城市,也會傳回「political」,表示它是政治實體。

  • formatted_address 這個字串包含這個位置的人類可讀地址。通常,這個地址即等於「郵政地址」,有時郵寄地址會因為國家/地區而不同 (請注意,因為授權限制,部分國家/地區 (例如英國) 並不允許散佈真實的郵政地址)。這個地址一般是由一或多個「地址元件」所組成。舉例來說,「111 8th Avenue, New York, NY」這個地址就包含「111」(街道號碼)、「8th Avenue」(路線)、「New York」(城市名稱) 和「NY」(美國州名) 等個別地址元件。這些地址元件包含下列其他資訊。

  • address_components[] 是一個陣列,包含上述的個別地址元件。每一個 address_component 通常包含以下各項:

    • types[] 這個陣列會指出地址元件的「類型」。
    • long_name 是 Geocoder 所傳回地址元件的完整文字說明或名稱。
    • short_name 是地址元件的縮寫文字名稱 (如果有的話)。例如,Alaska 州的地址元件中 long_name 為「Alaska」,而 short_name 則為 2 個字母的郵政簡碼「AK」。

    請注意,address_components[] 包含的地址元件數量可能會超過 formatted_address 中註明的數量。

  • geometry 包含下列資訊:

    • location 包含地理編碼的經緯度值。進行一般的地址查閱時,這個欄位通常是最重要的。
    • location_type 會儲存指定位置的其他相關資料,目前所支援的值如下:

      • "ROOFTOP" 表示傳回的結果是精準的地理編碼,因為結果中位置資訊的精確範圍已縮小至街道地址。
      • "RANGE_INTERPOLATED" 表示傳回的結果反映的是插入在兩個精確定點之間 (例如十字路口) 的約略位置 (通常會在街道上)。如果 Geocoder 無法取得街道地址的精確定點地理編碼,就會傳回插入的結果。
      • "GEOMETRIC_CENTER" 表示傳回的結果是結果的幾何中心,例如折線 (例如街道) 和多邊形 (區域)。
      • "APPROXIMATE" 表示傳回的結果是約略位置。
    • viewport 包含用來顯示傳回結果的建議檢視區,其範圍是透過兩個經緯度值加以指定,分別定義檢視區邊框的 southwest 角和 northeast 角。一般來說,檢視區是指您對使用者顯示結果時,用於結果的邊框。
    • bounds (選擇性傳回) 會儲存可完全容納傳回結果的邊框。請注意,這些邊界可能會不同於所建議的檢視區 (舉例來說,舊金山行政區涵蓋 法拉隆群島,雖然這在技術上是舊金山的一部分,但是可能不會傳回到檢視區中)。
  • partial_match 表示 Geocoder 並未傳回與原始要求完全相符的結果,但與要求的地址部分相符。建議您檢查原始要求,看看是否有拼寫錯誤和/或不完整的地址。最常發生部分相符的原因是,您在要求中傳送的街道地址不存在。

我們無法保證 Geocoding API 要求個別回應所使用的確切格式,因此請切勿假設元素的位置是絕對位置 (而且 Geocoding API 回應中的 address_components 數量會隨著要求的地址和時間的變動而改變)。相反地,您應該對回應進行「剖析」並透過「運算式」選取適當的值。如需詳細資訊,請參閱剖析網路服務回應

地址元件類型

傳回結果內的 types[] 陣列會指出「地址類型」。這些類型也可能透過 address_components[] 陣列傳回,以指出特定地址元件的類型。Geocoder 中的地址可以擁有多種類型;我們可以將這些類型視為「標記」。例如,許多城市都會加上 politicallocality 類型標記。

HTTP Geocoder 支援且會傳回下列類型:

  • street_address 表示精確的街道地址。
  • route 表示具名的路線 (例如「US 101」)。
  • intersection 表示主要的十字路口,通常是兩條主要道路的交會路口。
  • political 表示政治實體。通常,這個類型會顯示某些公家機關建築物的多邊形。
  • country 表示國家/地區政治實體,且通常是 Geocoder 所能傳回的最高順位類型。
  • administrative_area_level_1 表示國家等級之下的第一順位政治體。在美國境內,這些行政等級是指州。有些國家並未設有這些行政等級。
  • administrative_area_level_2 表示國家等級之下的第二順位政治體。在美國境內,這些行政等級是指郡。有些國家並未設有這些行政等級。
  • administrative_area_level_3 表示國家等級之下的第三順位政治體。這種類型表示次級行政區。有些國家並未設有這些行政等級。
  • colloquial_area 表示實體的常用替代名稱。
  • locality 表示自治城市或鄉鎮的政治實體。
  • sublocality 表示城市等級底下的第一順位政治體。
  • neighborhood 表示具名的社區。
  • premise 表示具名的位置,通常是著名的建築物或建築物群。
  • subpremise 表示具名位置底下的第一順位實體,通常是著名建築物群中的單一建築物。
  • postal_code 表示國家/地區郵政地址所使用的郵遞區號。
  • natural_feature 表示重要的自然地圖項。
  • airport 表示機場。
  • park 表示具名的公園。
  • point_of_interest 表示具名的名勝地點。通常這些「名勝地點 (POI)」是指不適合歸到其他分類的當地重要景點,如「帝國大廈」或「自由女神像」。

除了上述類型以外,地址元件也可能顯示下列類型:

  • post_box 表示特定的郵政信箱。
  • street_number 表示精確的街道號碼。
  • floor 表示建築物地址的樓層。
  • room 表示建築物地址的房號。

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

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

Geocoding API 支援直接使用 latlng 參數執行反向地理編碼。例如,以下查詢包含 Brooklyn 某處的經緯度值:

http://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452&sensor=true_or_false

注意:透過 latlng 參數傳送經緯度值時,請確定兩者之間沒有任何空格。

這項查詢會傳回下列結果:

{
  "status": "OK",
  "results": [ {
    "types": street_address,
    "formatted_address": "275-291 Bedford Ave, Brooklyn, NY 11211, USA",
    "address_components": [ {
      "long_name": "275-291",
      "short_name": "275-291",
      "types": street_number
    }, {
      "long_name": "Bedford Ave",
      "short_name": "Bedford Ave",
      "types": route
    }, {
      "long_name": "New York",
      "short_name": "New York",
      "types": [ "locality", "political" ]
    }, {
      "long_name": "Brooklyn",
      "short_name": "Brooklyn",
      "types": [ "administrative_area_level_3", "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
    } ],
    "geometry": {
      "location": {
        "lat": 40.7142298,
        "lng": -73.9614669
      },
      "location_type": "RANGE_INTERPOLATED",
      "viewport": {
        "southwest": {
          "lat": 40.7110822,
          "lng": -73.9646145
        },
        "northeast": {
          "lat": 40.7173774,
          "lng": -73.9583193
        }
      }
    }
  },

  ... Additional results[] ...

請注意,反向 Geocoder 會傳回一個以上的結果。結果的 "formatted_addresses" 不僅可以是郵政地址,也可以是任何一種位置的地理命名方式。舉例來說,為芝加哥市的某個定點進行地理編碼時,這個地理編碼定點可以採用街道地址、城市 (芝加哥)、州名 (伊利諾州) 或國家/地區 (美國) 進行標示。對 Geocoder 而言,這些都是「地址」。反向地理編碼會傳回任一類型,做為有效的結果。

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

下方將顯示先前查詢所傳回的完整 formatted_address 清單。

"formatted_address": "275-291 Bedford Ave, Brooklyn, NY 11211, USA",
"formatted_address": "Williamsburg, NY, USA",
"formatted_address": "New York 11211, USA",
"formatted_address": "Kings, New York, USA",
"formatted_address": "Brooklyn, NY, USA",
"formatted_address": "New York, NY, USA",
"formatted_address": "New York, USA",
"formatted_address": "United States"

一般而言,傳回的地址顯示方式會由最明確的排列至最不明確的;在這個案例中,最精確的地址將是最重要的結果。請注意,我們會傳回不同類型的地址,包括最具體的街道地址以及較籠統的政治實體,例如社區、城市、郡、州/省和國家/地區等。如果您想找出較籠統的地址,建議您檢查傳回的 Placemark"types" 欄位 (請參閱上方的地址元件類型)。

注意:反向地理編碼只是一個估計值。Geocoder 將在容許的範圍內,嘗試找出最接近的地址位置;如果找不到任何符合的項目,Geocoder 就會傳回零個結果。

檢視區自訂調整

您也可以指示「地理編碼」服務在指定檢視區內 (以邊框範圍表示) 顯示偏好的結果。只要在要求網址內設定 bounds 參數,即可達成這個效果。請注意,自訂調整會「優先」採用範圍內的結果;如果在這些範圍之外另有更相關的結果,也會一併納入。

bounds 參數定義了此邊框的西南角和東北角的經/緯度座標,並以直立線 (|) 字元來分隔座標。

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

要求:

http://maps.googleapis.com/maps/api/geocode/json?address=Winnetka&sensor=false

回應:

{
  "status": "OK",
  "results": [ {
    "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": {
        "lat": 42.1083080,
        "lng": -87.7417070
      },
      "location_type": "APPROXIMATE",
      "viewport": {
        "southwest": {
          "lat": 42.0917501,
          "lng": -87.7737218
        },
        "northeast": {
          "lat": 42.1248616,
          "lng": -87.7096922
        }
      },
      "bounds": {
        "southwest": {
          "lat": 42.0885320,
          "lng": -87.7715480
        },
        "northeast": {
          "lat": 42.1284090,
          "lng": -87.7110160
        }
      }
    }
  } ]
}

不過,如果我們藉由新增 bounds 引數,將邊框範圍定義在洛杉磯的聖佛南多谷 (San Fernando Valley),那麼這個地理編碼將會傳回該位置的「Winnetka」社區:

要求:

http://maps.googleapis.com/maps/api/geocode/json?address=Winnetka&bounds=34.172684,-118.604794|34.236144,-118.500938&sensor=false

回應:

{
  "status": "OK",
  "results": [ {
    "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": {
        "lat": 34.2131710,
        "lng": -118.5710220
      },
      "location_type": "APPROXIMATE",
      "viewport": {
        "southwest": {
          "lat": 34.1947148,
          "lng": -118.6030368
        },
        "northeast": {
          "lat": 34.2316232,
          "lng": -118.5390072
        }
      },
      "bounds": {
        "southwest": {
          "lat": 34.1791050,
          "lng": -118.5883200
        },
        "northeast": {
          "lat": 34.2353090,
          "lng": -118.5534191
        }
      }
    }
  } ]
}

區域自訂調整

傳送要求的所在區域 (通常是國家/地區) 會影響 Google Geocoding API 傳回的地址結果。舉例來說,從美國網域跟從西班牙網域傳送的「San Francisco」搜尋,可能會傳回不同的結果。

您也可以使用 region 參數,讓 Geocoding API 只傳回特定區域的結果。這個參數接受的 ccTLD (國家/地區代碼頂層網域) 引數,可用於指定區域自訂調整。多數 ccTLD 代碼與 ISO 3166-1 代碼相同,只有少數例外。例如,英國的 ccTLD 是「uk」(.co.uk),而其 ISO 3166-1 代碼卻是「gb」(在技術上代表「大不列顛暨北愛爾蘭聯合王國」的正式國名)。

您可在每個已正式啟用主要 Google 地圖應用程式的網域中,調整地理編碼的結果。請注意,自訂調整會「優先」採用特定網域的結果;如果在此網域之外另有更相關的結果,也會一併納入。

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

http://maps.googleapis.com/maps/api/geocode/json?address=Toledo&sensor=false
# Returns:
#
{
  "status": "OK",
  "results": [ {
    "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" ]
    } ],
    "geometry": {
      "location": {
        "lat": 41.6529200,
        "lng": -83.5777820
      },
      "location_type": "APPROXIMATE",
      "viewport": {
        "southwest": {
          "lat": 41.5861889,
          "lng": -83.7058414
        },
        "northeast": {
          "lat": 41.7195821,
          "lng": -83.4497226
        }
      },
      "bounds": {
        "southwest": {
          "lat": 41.5803170,
          "lng": -83.6947540
        },
        "northeast": {
          "lat": 41.7326310,
          "lng": -83.4545660
        }
      }
    }
  } ]
}

如果設定 region=es (西班牙),「Toledo」的地理編碼將傳回西班牙的城市:

http://maps.googleapis.com/maps/api/geocode/json?address=Toledo&sensor=false&region=es
#
# Returns
#
{
  "status": "OK",
  "results": [ {
    "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" ]
    } ],
    "geometry": {
      "location": {
        "lat": 39.8567775,
        "lng": -4.0244759
      },
      "location_type": "APPROXIMATE",
      "viewport": {
        "southwest": {
          "lat": 39.7882200,
          "lng": -4.1525353
        },
        "northeast": {
          "lat": 39.9252666,
          "lng": -3.8964165
        }
      },
      "bounds": {
        "southwest": {
          "lat": 39.8105550,
          "lng": -4.1796354
        },
        "northeast": {
          "lat": 39.9250920,
          "lng": -3.8147915
        }
      }
    }
  } ]
}

元件篩選

Google Geocoding API 可以傳回限制在特定地區的地址結果。您可以透過 components 篩選器指定限制的地區。篩選器可包含以直立線 (|) 隔開的 component:value 組合清單。系統只會傳回符合所有篩選器的結果。篩選器的值與其他地理編碼要求支援相同的拼字修正和部分相符處理方法。如果地理編碼的結果與某個元件篩選器部分相符,就會在回應中包含一個 partial_match 欄位。

可進行篩選的 components 包括:

  • route 符合路線的完整或簡短名稱。
  • locality 同時符合 localitysublocality 類型。
  • administrative_area 符合所有 administrative_area 等級。
  • postal_code 符合 postal_codepostal_code_prefix
  • country 符合國家/地區名稱或兩個字母的 ISO 3166-1 國碼。

「Santa Cruz」加上 components=country:ES 的地理編碼會傳回「Santa Cruz de Tenerife in Canary Islands, Spain」:

http://maps.google.com/maps/api/geocode/json?address=santa+cruz&components=country:ES&sensor=false
#
# Returns
#
{
   "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" : "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, Spain",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 28.58939290,
                  "lng" : -16.11936290
               },
               "southwest" : {
                  "lat" : 28.40976910,
                  "lng" : -16.34359460
               }
            },
            "location" : {
               "lat" : 28.469810,
               "lng" : -16.25485580
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 28.58939290,
                  "lng" : -16.11936290
               },
               "southwest" : {
                  "lat" : 28.40976910,
                  "lng" : -16.34359460
               }
            }
         },
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

內含元件篩選器的查詢只會傳回與篩選器相符的地理編碼結果。如果找不到相符的項目,Geocoder 會傳回符合篩選器本身的結果。

http://maps.google.com/maps/api/geocode/json?address=Torun&components=administrative_area:TX|country:US&sensor=false
#
# Returns
#
{
   "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.5007040,
                  "lng" : -93.50803900000001
               },
               "southwest" : {
                  "lat" : 25.83716390,
                  "lng" : -106.6456460
               }
            },
            "location" : {
               "lat" : 31.96859880,
               "lng" : -99.90181310
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 36.68395670,
                  "lng" : -91.70601210
               },
               "southwest" : {
                  "lat" : 26.99809190,
                  "lng" : -108.09761410
               }
            }
         },
         "types" : [ "administrative_area_level_1", "political" ]
      }
   ],
   "status" : "OK"
}

只有當您提供的篩選器互相排斥時,元件篩選才會傳回 ZERO_RESULTS 回應。

http://maps.google.com/maps/api/geocode/json?components=administrative_area:TX|country:FR&sensor=false
#
# Returns
#
{
   "results" : [],
   "status" : "ZERO_RESULTS"
}

使用 components 篩選器時,您不需提供地址參數就可以進行查詢,但是要指定元件,就必須提供一個值。

http://maps.google.com/maps/api/geocode/json?components=route:Annegatan|administrative_area:Helsinki|country:Finland&sensor=false
#
# Returns
#
{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Annegatan",
               "short_name" : "Annegatan",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Helsinki",
               "short_name" : "Helsinki",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Finland",
               "short_name" : "FI",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Annegatan, Helsinki, Finland",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 60.17088090,
                  "lng" : 24.94279590
               },
               "southwest" : {
                  "lat" : 60.16266270,
                  "lng" : 24.93114440
               }
            },
            "location" : {
               "lat" : 60.16693210,
               "lng" : 24.93683020
            },
            "location_type" : "GEOMETRIC_CENTER",
            "viewport" : {
               "northeast" : {
                  "lat" : 60.17088090,
                  "lng" : 24.94279590
               },
               "southwest" : {
                  "lat" : 60.16266270,
                  "lng" : 24.93114440
               }
            }
         },
         "types" : [ "route" ]
      }
   ],
   "status" : "OK"
}

需要進行驗證

您必須登入 Google+ 才能執行這項操作。

正在登入...

Google 開發人員需要您的授權才能執行這項操作。