從 Geocoding v3 遷移至 v4

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

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

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

您可以在新的 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 > 1)。
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 > 1)。
新功能	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 回應中呈現這些功能時的差異。

警告： 與 Geocoding API 第 3 版和其他 Geocoding API 第 4 版方法不同，「SearchDestinations」端點可能會傳回沒有精確主要地址的結果。如果只需要精確主要地址的結果，請在要求中將 placeFilter.addressability 設為 PRIMARY。

進入

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

請注意，entrance 的格式與 Geocoding API 第 3 版的進入格式略有不同。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 檢查是否為建築物。placeView.structureType 欄位。如果結構類型為 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 第 3 版未列出的理由。

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