從 Geocoding v3 遷移至 v4

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

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

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

您可以在新的 v4 方法中使用現有的 API 金鑰。不過，如果您已要求提升 API 第 3 版的配額，則必須要求提升新版第 4 版 API 的配額。

警告： 基於安全風險，您不應直接從用戶端 JavaScript 呼叫 Geocoding API 第 4 版方法。如果違反建議，請注意，要求提高配額可能會增加 API 金鑰濫用的影響。使用用戶端公開的 API 金鑰呼叫 Geocoding API v4 時，風險極高。詳情請參閱「安全性考量」。

從 v3 正向地理編碼遷移

如果您使用 v3 地理編碼服務對地址進行地理編碼，請遷移至 v4 的「對地址進行地理編碼」方法，該方法會接受 GET 要求。

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

警告： 在所有第 4 版方法中，欄位名稱都採用小寫駝峰式大小寫格式 (例如 addressComponents)，與第 3 版方法使用的蛇形命名法 (例如 address_components) 不同。第 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 反向地理編碼遷移

如果您使用 v3 反向地理編碼將座標轉換為地址，請改用 v4 的「反向地理編碼位置」方法，該方法接受 GET 要求。

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

警告： 在所有第 4 版方法中，欄位名稱都採用小寫駝峰式大小寫格式 (例如 addressComponents)，與第 3 版方法使用的蛇形命名法 (例如 address_components) 不同。第 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 物件。

從第 3 版地址描述元遷移

如果您使用 address_descriptor 透過 Geocoding v3 取得地點的額外資訊，請改用SearchDestinationsResponse 的 landmarks 欄位。

從 v3 Place 地理編碼遷移

如果您使用 place_id 透過 Geocoding v3 取得特定地點 ID 的位址，請遷移至 v4 Place Geocoding 方法，該方法接受 GET 要求。

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

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

要求參數變更

v3 參數	v4 參數	附註
place_id	要求 proto 中的 place 欄位	地點 ID 現在會以路徑參數 places/{place} 的形式提供，例如：https://geocode.googleapis.com/v4/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 v4 的 SearchDestinations 方法將取代 Geocoding API v3 的下列功能：

• 進入
• 導航點
• 建築物外框
• 園區

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

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

進入

如要取得與 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 欄位，檢查每個 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 欄位。destination您可以透過 placeView.structureType 欄位，檢查每個 placeView 是否為理由。如果結構類型為 GROUNDS，您可以從 placeView.displayPolygon 欄位取得大綱。placeView 也會提供其他欄位，說明 Geocoding API 第 3 版未提供的理由。

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

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

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

結果精確度

在 Geocoding API v3 中，回應幾何圖形中的 location_type 欄位會指出結果的精確度，部分用戶端會根據這些值 (ROOFTOP、RANGE_INTERPOLATED、GEOMETRIC_CENTER 和 APPROXIMATE) 排序或篩選結果。在標準 Geocoding API v4 遷移作業中，這個欄位會重新命名為 granularity。

在 Destinations API (v4 SearchDestinations) 中，沒有 location_type 欄位。而是以不同方式處理空間資訊：

• 不需要手動篩選用戶端：標準地理編碼服務會提供不同精細程度的多個結果，但 SearchDestinations 方法會盡可能解析為單一最佳目的地，減少模糊不清的情況。這樣一來，用戶就不必依位置類型篩選，即可判斷哪個結果最合適。
• 以結構類型和顯示多邊形表示的空間資訊： 空間幾何和結構會以以下方式表示：
  • displayPolygon (適用於精確幾何圖形)。
  • placeView 物件中的 structureType 欄位。
• 結構類型對應：
  • structureType、BUILDING 或 SECTION 的 POINT 通常對應於先前稱為 ROOFTOP 的項目。
  • structureType 的 GROUNDS 通常會對應至 GEOMETRIC_CENTER。

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

如「選擇要傳回的欄位」一文所述，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/v4/geocode/destinations

安全性考量

Geocoding API 第 4 版是設計為伺服器對伺服器 API。JavaScript 使用者無法直接從第 3 版遷移至第 4 版。使用 API 金鑰直接從用戶端 JavaScript (例如瀏覽器) 呼叫 v4 方法，會導致 API 金鑰遭竊和濫用的風險大幅提高。

HTTP 參照網址限制雖然實用，但對於網路服務端點來說，保護力仍不足，因為攻擊者可以輕易略過這項限制，在要求中偽造 Referer 標頭。

建議做法

建議您透過自己的後端伺服器使用 Geocoding API 第 4 版。您的用戶端應用程式應向這個中介伺服器提出要求，然後中介伺服器會使用受保護的 API 金鑰 (例如儲存在環境變數或密鑰管理工具中的金鑰)，安全地呼叫 Google API。確保 API 金鑰絕不會在前端程式碼中曝光。

滿足用戶端需求的替代方案

如果您有用戶端需求，需要進行地理編碼，請考慮使用現有的用戶端解決方案：

• Maps JavaScript API 中的地理編碼服務：地理編碼服務會繼續使用 v3 後端，且專為瀏覽器環境設計。
• Places UI Kit：使用 Places UI Kit，包括Place Autocomplete 元素，取得地址相關使用者介面元素。