從 Geocoding v3 遷移至 v4

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

如果您的帳單地址位於歐洲經濟區，自 2025 年 7 月 8 日起，使用服務時將適用《 Google 地圖平台歐洲經濟區服務條款》。功能會因區域而異。 瞭解詳情。

Geocoding API 第 4 版推出多個新端點，取代第 3 版 API 的功能。本指南說明如何遷移應用程式，改用新的第 4 版端點。

您可以在新的 v4 端點中使用現有的 API 金鑰。不過，如果您已要求提高 API 第 3 版的配額，則必須要求提高新版第 4 版 API 的配額。JavaScript 使用者無法遷移。

注意：在預先發布版中，Geocoding API 第 4 版方法每秒最多只能執行 25 次查詢。如要瞭解如何申請提高配額，請參閱「 查看及管理配額」，然後選取「Geocoding API」做為服務。

從 v3 正向地理編碼遷移

如果您使用地理編碼服務對地址進行地理編碼，請改用 v4 版本的「對地址進行地理編碼」端點，該端點接受 GET 要求。

v4 版 API 變更了多個參數的名稱、結構和支援項目。強烈建議您使用欄位遮罩，指定要在回應中傳回的欄位。

警告： 在所有第 4 版端點中，欄位名稱的格式都是小寫駝峰式大小寫 (例如 addressComponents)，與使用蛇形命名法 (例如 address_components) 的第 3 版端點不同。第 4 版的 RPC 回應仍會使用蛇形命名法，與第 3 版相同。

要求參數變更

v3 參數	v4 參數	附註
address、components	address	非結構化地址 (v3 address) 現在會透過網址路徑傳遞。元件篩選器 (v3 components) 現在會以 address.* 查詢參數的形式傳遞。
bounds	locationBias.rectangle	已重新命名，結構已變更為物件。
language	languageCode	已重新命名。
region	regionCode	已重新命名。
extra_computations	已移除

回應欄位變更

v3 欄位	第 4 版欄位	附註
status、error_message	已移除	第 4 版使用 HTTP 狀態碼和錯誤主體。
results.address_components.long_name/results.address_components.short_name	results.addressComponents.longText/results.addressComponents.shortText	已重新命名。
results.geometry.location_type	results.granularity	已重新命名。
results.geometry.location	results.location	欄位名稱：lat/lng -> latitude/longitude。
results.geometry.viewport	results.viewport	欄位名稱：northeast/southwest -> high/low。
results.postcode_localities	results.postalCodeLocalities	已重新命名。現在會針對一或多個地區傳回 (必須使用 v3 以上版本)。
results.partial_match	已移除
新功能	results.addressComponents.languageCode	特定地址元件的語言。
新功能	results.bounds	使用 high/low 明確設定界線。
新功能	results.place	地點的資源名稱。
新功能	results.postalAddress	結構化 PostalAddress 物件。

從 v3 反向地理編碼遷移

如果您使用反向地理編碼將座標轉換為地址，請遷移至 v4 版本的「反向地理編碼位置」端點，該端點接受 GET 要求。

v4 版 API 變更了多個參數的名稱、結構和支援項目。強烈建議您使用欄位遮罩，指定要在回應中傳回的欄位。

警告： 在所有第 4 版端點中，欄位名稱的格式都是小寫駝峰式大小寫 (例如 addressComponents)，與使用蛇形命名法 (例如 address_components) 的第 3 版端點不同。第 4 版的 RPC 回應仍會使用蛇形命名法，與第 3 版相同。

要求參數變更

v3 參數	v4 參數	附註
language	languageCode	已重新命名。
region	regionCode	已重新命名。
result_type	types	已重新命名，使用重複的查詢參數。
location_type	granularity	已重新命名，使用重複的查詢參數。
extra_computations	已移除

回應欄位變更

v3 欄位	第 4 版欄位	附註
status、error_message	已移除	第 4 版使用 HTTP 狀態碼和錯誤主體。
results.address_components.long_name/results.address_components.short_name	results.addressComponents.longText/results.addressComponents.shortText	已重新命名。
results.geometry.location_type	results.granularity	已重新命名。
results.geometry.location	results.location	欄位名稱：lat/lng -> latitude/longitude。
results.geometry.viewport	results.viewport	欄位名稱：northeast/southwest -> high/low。
新功能	results.addressComponents.languageCode	特定地址元件的語言。
新功能	results.bounds	使用 high/low 明確設定界線。
新功能	results.place	地點的資源名稱。
新功能	results.postalAddress	結構化 PostalAddress 物件。

從 v3 地點地理編碼遷移

如果您使用 place_id 搭配 Geocoding v3 取得特定地點 ID 的地址，請遷移至 v4 Place Geocoding 端點，該端點接受 GET 要求。

v4 版 API 變更了多個參數的名稱、結構和支援項目。強烈建議您使用欄位遮罩，指定要在回應中傳回的欄位。

警告： 在所有第 4 版端點中，欄位名稱的格式都是小寫駝峰式大小寫 (例如 addressComponents)，與使用蛇形命名法 (例如 address_components) 的第 3 版端點不同。第 4 版的 RPC 回應仍會使用蛇形命名法，與第 3 版相同。

要求參數變更

v3 參數	v4 參數	附註
place_id	要求 proto 中的 place 欄位	地點 ID 現在會以路徑參數 places/{place} 的形式提供，例如：https://geocode.googleapis.com/v4beta/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw。這會對應至基礎要求中的地點欄位。
language	languageCode	已重新命名。
region	regionCode	已重新命名。

回應欄位變更

v3 欄位	第 4 版欄位	附註
status、error_message	已移除	第 4 版使用 HTTP 狀態碼和錯誤主體。
results	(根目錄)	第 4 版會傳回單一結果物件，而非 results 陣列。
results.address_components.long_name/results.address_components.short_name	addressComponents.longText/addressComponents.shortText	已重新命名。
results.geometry.location_type	granularity	已重新命名。
results.geometry.location	location	欄位名稱：lat/lng -> latitude/longitude。
results.geometry.viewport	viewport	欄位名稱：northeast/southwest -> high/low。
results.postcode_localities	postalCodeLocalities	已重新命名。現在會針對一或多個地區傳回 (必須使用 v3 以上版本)。
新功能	addressComponents.languageCode	特定地址元件的語言。
新功能	bounds	使用 high/low 明確設定界線。
新功能	place	地點的資源名稱。
新功能	postalAddress	結構化 PostalAddress 物件。

從 Geocoding Hyperlocal Data 遷移至目的地

Geocoding API v3 中的下列功能將由 Geocoding API v4 的 SearchDestinations 端點取代：

• 進入
• 導航點
• 建築物輪廓
• 園區

如果您使用 Geocoding API v3 取得上述功能，請參閱這份文件，改用 SearchDestinations 端點取得這些功能。本文說明如何在 SearchDestinations API 回應中找到這些功能，以及 Geocoding API v3 和 Geocoding API v4 的 SearchDestinations 端點，在 API 回應中呈現這些功能時的差異。

進入

如要取得與 destination 相關聯的入口，請使用 destination.entrances 欄位。

請注意，entrance 的格式與 Geocoding API v3 中的進入格式略有不同。destination.entrances 中的每個入口都包含下列欄位：

• displayName：這是新的選用欄位，可讓使用者瞭解入口名稱，例如「B 閘門」。
• location - 這是 LatLng 類型的位置，與 Geocoding API v3 中使用的格式不同。
• tags - 這與 Geocoding API v3 中入口的 tags 欄位相同。
• place - 類似於 Geocoding API v3 中入口的 buildingPlaceId 欄位。不過，這個欄位中的地點 ID 可以是任何類型的地點，不一定只是建築物。

導航點

如要取得與 destination 相關聯的導覽點，請使用 destination.navigationPoints 欄位。

請注意，navigationPoint 的格式與 Geocoding API v3 中的導航點格式略有不同。destination.navigationPoints 中的每個導覽點都包含下列欄位：

• displayName：這是新的選填欄位，可為導航點提供使用者可理解的名稱，例如「5th Ave」。
• location - 這是 LatLng 類型的位置，與 Geocoding API v3 中使用的格式不同。
• travelModes - 這與 Geocoding API v3 中導航點的 restrictedTravelModes 欄位類似。可能的列舉值相同，唯一差別在於這個欄位現在代表導航點可接受的交通方式，而非受限的交通方式。
• usage：這是新欄位，內含導覽點支援的用途。請注意，大多數導覽點都會有 UNKNOWN 用法，但這不一定表示導覽點的用法受到任何限制。

建築物輪廓

如要取得與 destination 相關聯的建築物外框，請使用 destination 中代表建築物的 placeView 物件的 displayPolygon 欄位。您可以透過 placeView.structureType 欄位，檢查每個 placeView 是否為建築物。如果結構類型為 BUILDING，您可以從 placeView.displayPolygon 欄位取得大綱。placeView 也會提供 Geocoding API 第 3 版沒有的建築物額外欄位。

注意： 如要查看特定地點的建築物多邊形，您可以在要求中使用 placeFilter 參數縮小結果範圍。如要只傳回建築物結果，請在 placeFilter 中將 structureType 設為 "BUILDING"。如果取得多邊形是您的首要目標 (即使是沒有精確地址的地點)，請在 placeFilter 中將 addressability 設為 "ANY"，傳回最精確的多邊形。

範例

{
  "locationQuery": {
    "location": {
      "latitude": 37.4224,
      "longitude": -122.0841
    },
    "placeFilter": {
      "structureType": "BUILDING",
      "addressability": "ANY"
    }
  }
}
  

destination 可在下列欄位中包含代表建築物的 placeView 物件：

• destination.primary - 這是目的地的主要位置。
• destination.containingPlaces - 這是重複欄位，可容納「包含」主要地點的較大地點。舉例來說，如果主要地點是 subpremise，containingPlaces 通常會保留代表建築物的 placeView。
• destination.subDestinations - 這個重複欄位可保留主要地點的子目的地。例如建築物中的個別公寓單位。這個欄位通常不會有代表建築物的 placeView。

請注意，placeView.displayPolygon 的格式與 Geocoding API 第 3 版中的建築物外框格式相同，也就是採用 RFC 7946 格式的 GeoJSON 格式。

園區

與建構大綱類似，如要取得與 destination 相關聯的根據，您應使用 destination 中代表根據的 placeView 物件的 displayPolygon 欄位。針對每個 placeView，您可以透過 placeView.structureType 欄位檢查是否為理由。如果結構類型為 GROUNDS，您可以從 placeView.displayPolygon 欄位取得大綱。placeView 也會提供其他欄位，說明 Geocoding API v3 中未列出的理由。

destination 可包含 placeView 物件，代表下列欄位中的理由：

• destination.primary
• destination.containingPlaces
• destination.subDestinations

請注意，placeView.displayPolygon 的格式與 Geocoding API v3 中的地表輪廓格式相符，也就是採用 RFC 7946 格式的 GeoJSON 格式。

使用欄位遮罩要求這些功能

如「選擇要傳回的欄位」一文所述，SearchDestinations 端點需要欄位遮罩。您可以將欄位遮罩設為 *，傳回所有欄位，也可以設為要接收的特定欄位。舉例來說，下列 API 要求會設定欄位遮罩，以接收取得目的地入口、導覽點、建築物外框和地面所需的所有欄位：

curl -X POST -d '{"place": "places/ChIJG3kh4hq6j4AR_XuFQnV0_t8"}' \
  -H "X-Goog-Api-Key: API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Goog-FieldMask: destinations.entrances,destinations.navigationPoints,destinations.primary,destinations.containingPlaces,destinations.subDestinations" \
  https://geocode.googleapis.com/v4alpha/geocode/destinations