為地址進行地理編碼

歐洲經濟區 (EEA) 開發人員

地理編碼會將地址轉譯成地圖上的位置。對地址進行地理編碼時，回應會包含下列資訊：

地理編碼要求

地理編碼要求是 HTTP GET 要求。您可以將地址指定為非結構化字串：

https://geocode.googleapis.com/v4/geocode/address/ADDRESS_STRING

或是以結構化的地址元件集表示，並以查詢參數呈現：

https://geocode.googleapis.com/v4/geocode/address?STRUCTURED_ADDRESS

處理 HTML 表單中擷取的地址元件時，通常會使用結構化格式。

將所有其他參數做為網址參數傳遞，或針對 API 金鑰和欄位遮罩等參數，在標頭中做為 GET 要求的一部分傳遞。

傳遞非結構化地址字串

非結構化地址是指格式為字串或 Plus Code 的地址。地址地理編碼不會解析經緯度座標，也不會解析不代表地址或 Plus Code 的其他非結構化字串。系統不支援使用這類字串的要求，且可能會導致錯誤回應或不明行為。不支援的查詢範例如下：

查詢類型 範例
經緯度座標。請改用反向地理編碼。 "37.422131,-122.084801"
概念或限制過多，例如單一查詢中包含多個地點、道路或城市名稱 「Market Street San Francisco San Jose Airport」
Google 地圖未顯示郵政地址元素 「C/O John Smith 123 Main Street」
「P.O. Box 13 San Francisco」
商家、連鎖店或類別的名稱，加上這些實體不適用的地點 「德州達拉斯附近的 Tesco」
有多種解讀方式的模稜兩可查詢 「充電器退貨」
不再使用的舊名稱 "Middlesex United Kingdom"
非地理空間元素或意圖 「Ventura Harbor 有多少艘船？」
非官方或自訂名稱 「The Jenga」
「The Helter Skelter」

舉例來說，下列範例會傳遞網址編碼的地址字串「1600 Amphitheatre Parkway, Mountain View, CA」：

https://geocode.googleapis.com/v4/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA?key=API_KEY

請注意，網址中的「+」字元會轉換為空格。

您也可以使用 curl 指令提出要求：

curl -H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA"

地址可包含多種特殊字元。例如「/」，如「7/1 King St, Concord West」。將「/」編碼為 %2F：

https://geocode.googleapis.com/v4/geocode/address/7%2F1+King+St,+Concord+West
?key=API_KEY

另一個常見的例子是「#」字元，例如「9500 W Bryn Mawr Ave #650, Rosemont」。將「#」網址編碼為 %2FE：

https://geocode.googleapis.com/v4/geocode/address/9500+W+Bryn+Mawr+Ave+%23650,+Rosemont?key=API_KEY

在下一個範例中，您會將未經整理的地址字串指定為 Plus Code 849VCWC8+R4。請務必將「+」字元網址編碼為 %2B：

https://geocode.googleapis.com/v4/geocode/address/849VCWC8%2BR4?key=API_KEY

傳遞結構化地址

使用 address 查詢參數 (類型為 PostalAddress) 指定結構化地址。PostalAddress 物件可讓您在要求中，將部分或所有地址元件指定為個別查詢參數。

舉例來說，如要只指定您使用的地址郵遞區號，請使用 PostalAddress.postalCode：

https://geocode.googleapis.com/v4/geocode/address?address.postalCode=01062&key=API_KEY

如要指定多個地址元件 (例如在 HTML 表單中擷取的地址元件)，請使用多個查詢參數：

https://geocode.googleapis.com/v4/geocode/address?address.addressLines=1600+Amphithreater+Pkwy&address.locality=Mountain+View&address.administrativeArea=CA&key=API_KEY

使用 OAuth 提出要求

Geocoding API 第 4 版支援 OAuth 2.0 驗證。如要搭配 Geocoding API 使用 OAuth，OAuth 權杖必須指派正確的範圍。Geocoding API 支援下列範圍，可用於正向地理編碼：

  • https://www.googleapis.com/auth/maps-platform.geocode — 適用於所有 Geocoding API 方法。
  • https://www.googleapis.com/auth/maps-platform.geocode.address — 僅適用於正向地理編碼的 GeocodeAddress。

此外，您也可以為所有 Geocoding API 方法使用一般 https://www.googleapis.com/auth/cloud-platform 範圍。這個範圍在開發期間很有用，但不適用於正式環境，因為這是允許存取所有方法的一般範圍。

如需更多資訊和範例，請參閱「使用 OAuth」。

地理編碼回應

地理編碼會傳回 GeocodeAddressResponse 物件，其中包含 results 陣列的 GeocodeResult 物件。每個 GeocodeResult 物件都代表單一地點。

Geocoding API 回應會在 GeocodeResult 內的兩個主要位置包含 types 陣列：

  1. GeocodeResult.types：這個陣列會指出結果的整體類型。可能的值來自「地點類型 (新版)」頁面的表 A 和表 B。
  2. GeocodeResult.addressComponents[].types：每個地址元件都有 types 陣列，指出地址特定部分的類型。這些值來自「地點類型 (新版)」頁面的「地址類型和地址元件類型」表格。

完整的 JSON 物件格式如下：

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "location": {
        "latitude": 37.422010799999995,
        "longitude": -122.08474779999999
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.420656719708511,
          "longitude": -122.08547523029148
        },
        "high": {
          "latitude": 37.4233546802915,
          "longitude": -122.0827772697085
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "postalAddress": {
        "regionCode": "US",
        "languageCode": "en",
        "postalCode": "94043",
        "administrativeArea": "CA",
        "locality": "Mountain View",
        "addressLines": [
          "1600 Amphitheatre Pkwy"
        ]
      },
      "addressComponents": [
        {
          "longText": "1600",
          "shortText": "1600",
          "types": [
            "street_number"
          ]
        },
        {
          "longText": "Amphitheatre Parkway",
          "shortText": "Amphitheatre Pkwy",
          "types": [
            "route"
          ],
          "languageCode": "en"
        },
        ...
      ],
      "types": [
        "street_address"
      ],
      "plusCode": {
        "globalCode": "849VCWC8+R4",
        "compoundCode": "CWC8+R4 Mountain View, CA, USA"
      }
    }
  ]
}

必要參數

  • address：您要進行地理編碼的街道地址或 Plus Code。注意：地址地理編碼不會解析經緯度座標，或是不代表地址或 Plus Code 的其他非結構化字串。如要進一步瞭解不支援的查詢和相關示例，請參閱「傳遞非結構化地址字串」。按照相關國家/地區郵政服務使用的格式來指定地址。請避免提供額外的地址項目，例如商家名稱、住宅號碼、套房號碼或樓層號碼。街道地址元素應以空格分隔，並以網址編碼為 %20。舉例來說，如要傳遞「24 Sussex Drive Ottawa ON」地址，請使用下列格式： 
    24%20Sussex%20Drive%20Ottawa%20ON
     請按照下方格式輸入 Plus Code。加號在網址中會逸出為 %2B，空格則逸出為 %20：
    • 全球代碼是 4 個半形字元的區碼，加上 6 個半形字元以上的地區代碼。舉例來說，將「849VCWC8+R9」編碼為 849VCWC8%2BR9。
    • 複合代碼是 6 個半形字元以上的地區代碼，加上明確的位置。舉例來說，將「CWC8+R9 Mountain View, CA, USA」編碼為 CWC8%2BR9%20Mountain%20View%20CA%20USA。

選用參數

  • locationBias

    指定要搜尋的區域，做為 Viewport。 這個位置會做為自訂調整項，也就是說，系統可能會傳回指定位置附近的結果，包括該區域附近但不在區域內的結果。

    將區域指定為矩形檢視區塊。矩形是經緯度可視區域，以兩個對角相對的低點和高點表示。低點標記矩形的西南角，高點則代表矩形的東北角。

    可視區域視為封閉區域，因此包含邊界。緯度範圍必須介於 -90 到 90 度之間 (含首尾)，經度範圍則必須介於 -180 到 180 度之間 (含首尾)：

    • 如果 low = high，可視區域會由該單一點組成。
    • 如果 low.longitude > high.longitude，經度範圍會反轉 (可視區域會跨越 180 度的經度線)。
    • 如果 low.longitude = -180 度且 high.longitude = 180 度，則視埠會包含所有經度。
    • 如果 low.longitude = 180 度且 high.longitude = -180 度，經度範圍會空白。
    • 如果 low.latitude > high.latitude，緯度範圍會空白。

    最小值和最大值都必須填入，且代表的方塊不得為空。如果檢視區塊為空白，就會發生錯誤。

    舉例來說，這個查詢字串定義的檢視區塊會完整涵蓋紐約市：

    ?locationBias.rectangle.low.latitude=40.477398&locationBias.rectangle.low.longitude=-74.259087&locationBias.rectangle.high.latitude=40.91618&locationBias.rectangle.high.longitude=-73.70018

  • languageCode

    傳回結果時使用的語言。

    • 查看支援語言清單。Google 會經常更新支援的語言，因此這份清單可能不完整。
    • 如未提供 languageCode，API 會預設為 en。如果指定無效的語言代碼，API 會傳回 INVALID_ARGUMENT 錯誤。
    • API 會盡量提供使用者和當地人都能辨識的街道地址。為達成這個目標，系統會以當地語言傳回街道地址，並視需要根據偏好語言，將地址音譯為使用者可讀取的文字。所有其他地址都會以偏好語言顯示。地址元件一律會以同一種語言傳回，而該語言是從第一個元件中選擇。
    • 如果偏好語言沒有名稱，API 會使用最接近的名稱。
    • 偏好語言對 API 選擇傳回的結果集和傳回順序影響不大。地理編碼器會根據語言，以不同方式解讀縮寫，例如街道類型縮寫，或在某種語言中有效但在另一種語言中無效的同義字。

  • regionCode

    區域代碼，以 雙字元 CLDR 代碼值表示。沒有預設值。大多數 CLDR 代碼與 ISO 3166-1 代碼相同。

    對地址進行地理編碼 (正向地理編碼) 時，這個參數會影響服務傳回的結果，但不會完全限制結果只來自指定區域。進行地點或地點地理編碼時 (反向地理編碼或地點地理編碼)，這個參數可用來設定地址格式。在所有情況下，這個參數都可能根據適用法律影響結果。

  • FieldMask

    建立回應欄位遮罩，指定要在回應中傳回的欄位。使用網址參數 $fields 或 fields，或使用 HTTP 標頭 X-Goog-FieldMask，將回應欄位遮罩傳遞至方法。舉例來說，下列要求只會傳回回應的 placeID 欄位。

    curl -X GET -H 'Content-Type: application/json' \
-H 'X-Goog-FieldMask: results.placeId' \
-H "X-Goog-Api-Key: API_KEY" \
https://geocode.googleapis.com/v4/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA
    回覆內容如下： 
    {
  "results": [
    {
      "placeId": "ChIJiSSC8QK6j4AR98Thup8mqTc"
    }
  ]
}

    詳情請參閱「選擇要傳回的欄位」一節。

位置偏誤

使用 locationBias 參數，指示地理編碼服務優先顯示指定可視區域 (以定界框表示) 內的結果。locationBias 參數會定義這個定界框西南角和東北角的經緯度座標。

舉例來說，如果對「Washington」地址提出地理編碼要求，可能會傳回華盛頓特區和美國華盛頓州的結果：

https://geocode.googleapis.com/v4/geocode/address/Washington?key=API_KEY

回覆格式如下：

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
      "placeId": "ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
      "location": {
        "latitude": 38.9071923,
        "longitude": -77.0368707
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 38.7916449,
          "longitude": -77.119759
        },
        "high": {
          "latitude": 38.9958641,
          "longitude": -76.909393
        }
      },
      "bounds": {
        "low": {
          "latitude": 38.7916449,
          "longitude": -77.119759
        },
        "high": {
          "latitude": 38.9958641,
          "longitude": -76.909393
        }
      },
      "formattedAddress": "Washington, DC, USA",
      "addressComponents": [
        {
          "longText": "Washington",
          "shortText": "Washington",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        ...
      ],
      "types": [
        "locality",
        "political"
      ]
    },
    {
      "place": "//places.googleapis.com/places/ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
      "placeId": "ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
      "location": {
        "latitude": 47.7510741,
        "longitude": -120.7401386
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 45.543541,
          "longitude": -124.84897389999999
        },
        "high": {
          "latitude": 49.0024945,
          "longitude": -116.91607109999998
        }
      },
      "bounds": {
        "low": {
          "latitude": 45.543541,
          "longitude": -124.84897389999999
        },
        "high": {
          "latitude": 49.0024442,
          "longitude": -116.91607109999998
        }
      },
      "formattedAddress": "Washington, USA",
      "addressComponents": [
        {
          "longText": "Washington",
          "shortText": "WA",
          "types": [
            "administrative_area_level_1",
            "political"
          ],
          "languageCode": "en"
        },
      ...
      ],
      "types": [
        "administrative_area_level_1",
        "political"
      ]
    }
  ]
}

不過，如果我們透過新增 locationBias 參數的方式，將定界框定義在美國東北部，那麼這個地理編碼只會傳回華盛頓特區：

https://geocode.googleapis.com/v4/geocode/address/Washington?locationBias.rectangle.low.latitude=36.47&locationBias.rectangle.low.longitude=-84.72&locationBias.rectangle.high.latitude=43.39&locationBias.rectangle.high.longitude=-65.90&key=API_KEY

區域自訂調整

在地理編碼要求中，您可以使用 regionCode 參數，指示地理編碼服務優先傳回特定區域的結果。這個參數會採用 兩位字元的 CLDR 代碼值，指定區域偏誤。大多數 CLDR 代碼與 ISO 3166-1 代碼相同。

regionCode 沒有預設值。舉例來說，「Toledo」的地理編碼會傳回美國和西班牙的結果：

https://geocode.googleapis.com/v4/geocode/address/Toledo?key=API_KEY

回應：

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
      "placeId": "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
      "location": {
        "latitude": 41.652805199999996,
        "longitude": -83.5378674
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 41.579513,
          "longitude": -83.6944089
        },
        "high": {
          "latitude": 41.733036,
          "longitude": -83.4493851
        }
      },
      "bounds": {
        "low": {
          "latitude": 41.579513,
          "longitude": -83.6944089
        },
        "high": {
          "latitude": 41.733036,
          "longitude": -83.4493851
        }
      },
      "formattedAddress": "Toledo, OH, USA",
      "addressComponents": [
        {
          "longText": "Toledo",
          "shortText": "Toledo",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        ...
      ],
      "types": [
        "locality",
        "political"
      ]
    },
    {
      "place": "//places.googleapis.com/places/ChIJkwyrlqwLag0RiQIn2fdIshM",
      "placeId": "ChIJkwyrlqwLag0RiQIn2fdIshM",
      "location": {
        "latitude": 39.8628296,
        "longitude": -4.0273067
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 39.8116682,
          "longitude": -4.179933
        },
        "high": {
          "latitude": 39.9251319,
          "longitude": -3.8148935
        }
      },
      "bounds": {
        "low": {
          "latitude": 39.8116682,
          "longitude": -4.179933
        },
        "high": {
          "latitude": 39.9251319,
          "longitude": -3.8148935
        }
      },
      "formattedAddress": "Toledo, España",
      "addressComponents": [
        {
          "longText": "Toledo",
          "shortText": "Toledo",
          "types": [
            "administrative_area_level_4",
            "political"
          ],
          "languageCode": "es"
        },
        ...
      ],
      "types": [
        "administrative_area_level_4",
        "political"
      ]
    },
    ...
  ]
}

如果對「Toledo」發出地理編碼要求，並將 regionCode=es 設為西班牙，則只會傳回西班牙的結果：

https://geocode.googleapis.com/v4/geocode/address/Toledo?regionCode=es&key=API_KEY