地點地理編碼

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

地點地理編碼可讓您從地點 ID 擷取地址。

地點 ID 可以用來辨識 Google 地點介面集資料庫和 Google 地圖中的特定地點。對地址進行地理編碼時，系統會傳回地點 ID。您也可以從許多其他 API 擷取地點 ID，例如 Place Details (新版)、Text Search (新版) 和 Nearby Search (新版)。

發出地點地理編碼要求

地點地理編碼要求是 HTTP GET 要求，格式如下：

https://geocode.googleapis.com/v4beta/geocode/places/PLACE_ID

其中 PLACE_ID 包含感興趣地點的地點 ID。

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

https://geocode.googleapis.com/v4beta/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw?key=API_KEY

或是在 curl 指令中：

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4beta/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw"

使用 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.place - 僅與 GeocodePlace 搭配使用，進行地點地理編碼。

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

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

地點地理編碼回應

地點地理編碼會傳回代表地點 ID 對應地點的 GeocodeResult 物件。

完整的 JSON 物件格式如下：

{
  "place": "//places.googleapis.com/places/ChIJj61dQgK6j4AR4GeTYWZsKWw",
  "placeId": "ChIJj61dQgK6j4AR4GeTYWZsKWw",
  "location": {
    "latitude": 37.4220541,
    "longitude": -122.08532419999999
  },
  "granularity": "ROOFTOP",
  "viewport": {
    "low": {
      "latitude": 37.4209489697085,
      "longitude": -122.08846930000001
    },
    "high": {
      "latitude": 37.4236469302915,
      "longitude": -122.0829156
    }
  },
  "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"
    },
    {
      "longText": "Mountain View",
      "shortText": "Mountain View",
      "types": [
        "locality",
        "political"
      ],
      "languageCode": "en"
    },
    {
      "longText": "Santa Clara County",
      "shortText": "Santa Clara County",
      "types": [
        "administrative_area_level_2",
        "political"
      ],
      "languageCode": "en"
    },
    {
      "longText": "California",
      "shortText": "CA",
      "types": [
        "administrative_area_level_1",
        "political"
      ],
      "languageCode": "en"
    },
    {
      "longText": "United States",
      "shortText": "US",
      "types": [
        "country",
        "political"
      ],
      "languageCode": "en"
    },
    {
      "longText": "94043",
      "shortText": "94043",
      "types": [
        "postal_code"
      ]
    }
  ],
  "types": [
    "establishment",
    "point_of_interest"
  ]
}

必要參數

  • place：用於取得清楚易懂地址的地點 ID。地點 ID 是一組專屬 ID，可與其他 Google API 搭配使用。舉例來說，您可以提供 Roads API 傳回的 placeID，以取得對齊點的地址。如要進一步瞭解地點 ID，請參閱「地點 ID」。

選用參數

  • languageCode

    傳回結果時使用的語言。

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

  • regionCode

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

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