從 Geocoding v3 遷移至 v4

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

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

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

從 v3 正向地理編碼遷移

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

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

要求參數變更

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 變更了多個參數的名稱、結構和支援項目。強烈建議您使用欄位遮罩，指定要在回應中傳回的欄位。

要求參數變更

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 變更了多個參數的名稱、結構和支援項目。強烈建議您使用欄位遮罩，指定要在回應中傳回的欄位。

要求參數變更

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 v4 的 SearchDestinations 方法將取代 Geocoding API v3 的下列功能：

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

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

進入

如要取得與 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.structureType 欄位，檢查每個 placeView 是否為建築物。如果結構類型為 BUILDING，您可以從 placeView.displayPolygon 欄位取得大綱。placeView 也會提供 Geocoding API 第 3 版沒有的建築物額外欄位。

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/v4beta/geocode/destinations

安全性考量

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

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

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

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

如果您有需要地理編碼的用戶端需求，請考慮使用下列其中一個現有的用戶端解決方案：