設定 Geocoding API

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

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

本文說明開始使用 Geocoding API 的必要步驟。

1. 帳戶與帳單 確認符合先決條件。

2. 啟用 API 在 Google Cloud 專案中啟用 API。

3. 發出第一項要求 設定 API 金鑰或 OAuth，發出經過驗證的 API 要求。

重點：本設定指南包含設定 API 金鑰和建立 OAuth 權杖的程序。請選擇適用於部署環境的程序。

只有在 API 呼叫中加入 API 金鑰或 OAuth 權杖，才能使用 Google 地圖平台產品，這樣可以防止有人未經授權使用。

API 金鑰 OAuth 權杖

建立 OAuth 權杖

Geocoding API 支援使用 OAuth 2.0 進行驗證。Google 支援常見的 OAuth 2.0 使用情境，例如網路伺服器。

本文說明如何在開發環境中，將 OAuth 權杖傳遞至 Geocoding API 呼叫。如需在正式環境中使用 OAuth 的操作說明，請參閱「Google 的驗證方式」。

注意：

雖然您可以直接向伺服器發出 API 要求來使用 Google 地圖 API，但用戶端程式庫提供簡化功能，可大幅減少需要編寫的程式碼數量。Google 地圖提供多種程式語言的用戶端程式庫，包括 Go、Java、Node.js 和 Python。

如需說明文件和範例，請參閱「Geocoding API 用戶端程式庫」。

關於 OAuth

根據部署環境，您可以使用 OAuth 建立及管理存取權杖。

舉例來說，Google OAuth 2.0 系統支援伺服器對伺服器的互動行為，例如應用程式和 Google 服務之間的互動。在這種情況下，您需要服務帳戶，這類帳戶屬於應用程式，而非個別使用者。您的應用程式會代表服務帳戶呼叫 Google API，因此不會直接牽涉到使用者。如要進一步瞭解驗證方法，請參閱「Google 的驗證方式」。

或者，您也可以在 Android 或 iOS 行動應用程式中使用 Geocoding API。如要瞭解如何搭配使用 OAuth 與 Geocoding API，包括如何管理不同部署環境的存取權杖，請參閱「使用 OAuth 2.0 存取 Google API」。

關於 OAuth 範圍

如要搭配 Geocoding API 使用 OAuth，OAuth 權杖必須指派正確的範圍。Geocoding API 支援下列範圍：

• https://www.googleapis.com/auth/maps-platform.geocode — 適用於所有 Geocoding API 端點。
• https://www.googleapis.com/auth/maps-platform.geocode.address — 僅適用於正向地理編碼的 GeocodeAddress。
• https://www.googleapis.com/auth/maps-platform.geocode.location — 僅與 GeocodeLocation 搭配使用，用於反向地理編碼。
• https://www.googleapis.com/auth/maps-platform.geocode.place - 僅適用於 GeocodePlace，用於地點地理編碼。

此外，您也可以為所有 Geocoding API 端點使用一般 https://www.googleapis.com/auth/cloud-platform 範圍。這個範圍在開發期間很有用，因為使用 gcloud 建立權杖時，預設會使用這個範圍。

範例：在本機開發環境中嘗試 REST API 呼叫

如要使用 OAuth 權杖試用 Geocoding API，但沒有環境可產生權杖，請按照本節的程序進行呼叫。

本範例說明如何使用應用程式預設憑證 (ADC) 提供的 OAuth 權杖進行呼叫。如要瞭解如何使用 ADC 透過用戶端程式庫呼叫 Google API，請參閱「使用用戶端程式庫進行驗證」。

注意：下列發出 REST 呼叫的程序不適用於正式環境。請僅在開發或測試環境中使用此程序。

必要條件

使用 ADC 發出 REST 要求前，請先使用 Google Cloud CLI 將憑證提供給 ADC：

1. 安裝並初始化 gcloud CLI。

2. 在本機電腦上執行下列 gcloud 指令，建立憑證檔案：

   gcloud auth application-default login

3. 系統會顯示登入畫面。登入後，您的憑證會儲存在 ADC 使用的本機憑證檔案中。

詳情請參閱「為本機開發環境設定 ADC」。

發出 REST 要求

在本範例中，您會傳遞兩個要求標頭：

• 使用下列指令產生權杖，並在 Authorization 標頭中傳遞 OAuth 權杖：

  gcloud auth application-default print-access-token

  傳回的權杖範圍為 https://www.googleapis.com/auth/cloud-platform.

• 在 X-Goog-User-Project 標頭中，傳遞已啟用帳單功能的 Google Cloud 專案 ID 或名稱。

以下範例使用 OAuth 權杖呼叫 Geocoding API。

1. 編輯 PROJECT_ID 欄位，傳遞 Google Cloud 專案的 ID。

   curl -X GET -H 'Content-Type: application/json' \
   -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
   -H "X-Goog-User-Project: PROJECT_ID" \
   "https://geocode.googleapis.com/v4beta/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA"
   

2. 按一下程式碼範例中的複製圖示 ，即可複製 curl 指令。
3. 將指令貼到終端機視窗中，然後執行指令。

回應為 JSON 物件：

疑難排解

如果要求傳回的錯誤訊息指出這個 API 不支援使用者憑證，請參閱「排解 ADC 設定問題」。