遷移至 Google 地圖平台上的 Solar API

如要從 Google Earth Engine Solar API 改用 Google 地圖平台 Solar API，請按照下列步驟操作：

1. 在雲端專案中啟用 Google 地圖平台 Solar API。
2. 建立新的金鑰，並將其限制為 GMP Solar API。
3. 按照下方逐步操作說明更新程式碼。

並列比較

	Solar API (新版)	Earth Engine Solar API (已淘汰)
服務上線狀態	已推出	Pilot (已淘汰)
存取
機制	Google Cloud 帳戶 (透過 Cloud 控制台啟用 Solar API，並透過「Google 地圖平台」專區管理 API)	透過 Cloud 控制台啟用 Earth Engine Solar API，建立 Google Cloud 帳戶
參與者	公開	存取權控管
層級	自行佈建	Cloud 專案手動存取
驗證	API 金鑰和 OAuth	API 金鑰
定價
策略	即付即用	100% 折扣
分層	每 1, 000 次查詢，價格會根據查詢量遞減	–
端點	不同端點的價格	–
Cloud
監控	「Google 地圖平台」下方的「雲端監控」	「API 和服務」下方的「Cloud Monitoring」
配額	QPM (每分鐘查詢次數) 和 QPH (每小時查詢次數)	年約
記錄	Cloud Logging (選用)	Cloud Logging (選用)
帳單	Cloud Billing 帳戶	-
支援	提供完整的 Google 地圖平台支援服務，並設有服務等級目標/服務水準協議	受限，透過電子郵件
API
主機名稱	https://solar.googleapis.com/v1/ (REST)	https://earthenginesolar.googleapis.com/v1/ (REST)
方法	buildingInsights:findClosest dataLayers:get	buildings:findClosest solar.get
回應	與前測無異	–
solarInfo	半徑 ≤ 100 公尺	半徑 ≤ 100 公尺
涵蓋範圍
區域	全球	全球
資料品質	HIGH/MEDIUM	HIGH/MEDIUM
建築物類型	任何對應至地址且位於 Solar API 圖像範圍內的建築物	任何對應至地址且位於 Solar API 圖像範圍內的建築物
服務條款
《服務條款》	Google 地圖平台條款	Google Earth Engine 條款

操作方式

設定 Google Cloud 專案

請參閱「設定 Google Cloud 專案」一文中的操作說明。

注意： 請在「設定 Google Cloud 專案」的「啟用 API」部分停止操作。

只有特定角色可以建立 Cloud 專案；如果您無法建立專案，請與貴機構的管理員聯絡。

您也可以使用現有的 Cloud 專案。詳情請參閱「開始使用 Google 地圖平台」一文。

設定帳單帳戶

請參閱這篇文章，瞭解如何管理帳單帳戶。

您可以使用現有的 Cloud 專案和帳單帳戶。

取得 API 金鑰或使用 OAuth 權杖

設定 Google Cloud 專案後，請建立並妥善保管 API 金鑰，再使用 Solar API，如「使用 API 金鑰」一文所述。或者，您也可以按照「使用 OAuth」一節的說明建立 OAuth 權杖。

使用 Solar API

• 向新端點發出 GET 要求：https://solar.googleapis.com
• 請注意，部分 API 方法名稱已變更：
  • buildings:findClosest → buildingInsights:findClosest
  • solarinfo:get → dataLayers:get

快速試用：使用先前步驟儲存的 API 金鑰，並在瀏覽器中載入網址前，將下方範例查詢中的 YOUR_API_KEY 替換為該金鑰：

https://solar.googleapis.com/v1/dataLayers:get?location.latitude=37.2746464&location.longitude=-121.7530949&radius_meters=10&key=YOUR_API_KEY

針對原始預覽版的回應

針對 2023 年 5 月 9 日的原始預覽版，回應中的網址格式如下：

https://earthengine.googleapis.com/v1alpha/projects/sunroof-api/thumbnails/THUMBNAIL_ID:getPixels

以下程式碼片段是回應範例：

{
  "imageryDate": {
    "year": 2015,
    "month": 8,
    "day": 8
  },
  "imageryProcessedDate": {
    "year": 2021,
    "month": 2,
    "day": 15
  },
  "dsmUrl": "https://earthengine.googleapis.com/v1alpha/projects/geo-solar-api/thumbnails/fbde33e9cd16d5fd10d19a19dc580bc1-8614f599c5c264553f821cd034d5cf32:getPixels",
  "rgbUrl": "https://earthengine.googleapis.com/v1alpha/projects/geo-solar-api/thumbnails/91ed3551f2d0abee20af35e07bd0c927-c96c59e80cf1fc1dc86cf59fc8ec86ba:getPixels",
  "maskUrl": "https://earthengine.googleapis.com/v1alpha/projects/geo-solar-api/thumbnails/e4051553dba6870c03d855ae82c30b7e-7cc8ae6ce7c73f219e3c1924e5c17fc6:getPixels",
  "annualFluxUrl": "https://earthengine.googleapis.com/v1alpha/projects/geo-solar-api/thumbnails/9b0f87f49d778a65c9e27ff936e6dbba-b90be2fe80d25abd4c9e8c4dc809f763:getPixels",
  "monthlyFluxUrl": "https://earthengine.googleapis.com/v1alpha/projects/geo-solar-api/thumbnails/90e7cca77402f14809e349937f0a0be8-94fafeb4ef42d72f1b3c0652a1cb5518:getPixels",
  "hourlyShadeUrls": [
    "https://earthengine.googleapis.com/v1alpha/projects/geo-solar-api/thumbnails/dcd276e4782aef4ff1b230b781736d37-e193b231ce57a03449afc3e21cf6783b:getPixels",
    ...
  ]
  }

如要對回應中的網址提出要求，請在要求中加入整個網址。

這項要求和回應的完整規格可參閱參考文件。

編寫支援這兩種回應格式的應用程式

您現在可以編寫應用程式，同時處理原始的預覽和目前的回應格式。

除了實際網址本身，這兩種回應的主要差異在於，您必須將 API 金鑰傳遞至從新回應格式存取網址的要求。如果省略 API 金鑰，要求就會失敗。

注意： 請勿以原始格式將 API 金鑰傳遞至網址，也就是使用 https://earthengine.googleapis.com 網域的網址。將 API 金鑰傳遞至該網址會導致錯誤。

舉例來說，您可以將以下程式碼新增至應用程式，以便檢查網址並正確處理每個版本：

JavaScript

/**
* Function to examine a response URL and to append the API key to the
* URL if it is in the new format.
*/
function prepareGetGeoTiffUrl(geoTiffUrl, apiKey) {
  if (geoTiffUrl.match("solar.googleapis.com")) {
    let url = new URL(geoTiffUrl);
    url.searchParams.set('apiKey', apiKey);
    return url.toString();
  }
  return geoTiffUrl;
}

Python

# Functions to examine a response URL and to append the API key to the
# URL if it is in the new format.

def add_api_key_to_url(base_url: str, api_key: str) -> str:
  '''Formats URL that currently lacks an API key to use the one provided.'''
  return base_url + "&key=" +api_key;

def prepare_geo_tiff_url(base_url: str, api_key: str) -> str:
  '''Prepares URL from GetDataLayers depending on API being called.
    If the geoTIFF url from GetDataLayers is for the solar API GetGeoTiff
      endpoint, append the API key. Otherwise return the URL as is.
  '''
  if re.search("solar.googleapis.com", geo_tiff_url):
    return add_api_key_to_url(geo_tiff_url, api_key)
  return geo_tiff_url

Java

/** Adds API key to a URL. */
private String addApiKeyToUrl(String geoTiffUrl, String apiKey) {
  return geoTiffUrl + "&key=" + apiKey;
}

/**
* Function to examine a response URL and to append the API key to the
* URL if it is in the new format.
*/
private String prepareGetGeoTiffUrl(String geoTiffUrl, String apiKey) {
  Pattern pattern = Pattern.compile("solar.googleapis.com");
  Matcher matcher = pattern.matcher(geoTiffUrl);
  if (matcher.find()) {
    return addApiKeyToUrl(geoTiffUrl, apiKey);
  } else {
    return geoTiffUrl;
  }
}

監控

專案層級	帳單帳戶層級

實用訣竅

• 配額：可擴充的使用量 (而非會消失的年度使用量)
  • 目前配額，將變更為 QPM
  • 最佳做法：設定用戶端配額並傳送快訊
• 價格：
  • 即付即用
  • 如果位置不在涵蓋範圍內，系統不會向您收取 404 NOT_FOUND 回應的費用，但會計入配額
• 一般使用條款：《Google 地圖平台服務條款》