遷移至 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 (已淘汰)
服務上線狀態	已推出	前測 (已淘汰)
存取權
機制	透過 Cloud 控制台啟用 Solar API，並透過「Google 地圖平台」專區管理 API，藉此建立 Google Cloud 帳戶	透過 Cloud 控制台啟用 Earth Engine Solar API，藉此存取 Google Cloud 帳戶
對象	公開	存取控制
等級	自行佈建	Cloud 專案手動存取
驗證	API 金鑰和 OAuth	API 金鑰
定價
策略	Pay-as-you-go	100% 折扣
分層	每 1, 000 次查詢，並依據用量調降價格	–
端點	按照端點不同的價格	–
Cloud
監控	Cloud Monitoring：Google 地圖平台	Cloud Monitoring (位於「API 和服務」下方)
配額	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 圖像涵蓋範圍內的建築物
服務條款
TOS	Google 地圖平台條款	Google Earth Engine 條款

操作方式

設定 Google Cloud 專案

如需操作說明，請參閱設定 Google Cloud 專案。

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

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

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

設定帳單帳戶

如需操作說明，請參閱如何管理帳單帳戶。

您可以搭配現有帳單帳戶使用現有的 Cloud 專案，

取得 API 金鑰或使用 OAuth 權杖

設定 Google Cloud 專案後，您必須按照「使用 API 金鑰」一節的說明，建立並保護 API 金鑰以使用 Solar 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 金鑰傳送給從「new」回應格式存取網址的要求。如果您省略 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)
  • 最佳做法：設定用戶端配額及傳送快訊
• 定價：
  • Pay-as-you-go
  • 如果位置不在涵蓋範圍內，則為 404 NOT_FOUND 回應不會計費，但會耗用配額
• 一般使用條款：Google 地圖平台服務條款