遷移至 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 (已淘汰)
服務上線狀態	已推出	前測 (已淘汰)
存取
機制	Google Cloud 帳戶，方法是透過 Cloud 控制台啟用 Solar API，並透過「Google 地圖平台」專區管理 API	Google Cloud 帳戶，可透過 Cloud 控制台啟用 Earth Engine Solar API
參與者	公開	存取權控管
層級	已自行佈建	Cloud 專案手動存取
驗證	API 金鑰和 OAuth	API 金鑰
定價
策略	即付即用	100折扣
階層	每 1, 000 次查詢 (價格因用量降低)	–
端點	不同端點的價格	–
Cloud
監控	在「Google 地圖平台」底下使用 Cloud Monitoring	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 專案。

注意： 請在「Enable API」(啟用 API) 部分停止「設定 Google Cloud 帳戶」 。

只有特定角色可以 建立 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 日起，原始預覽版於 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
  • 最佳做法：設定用戶端配額及傳送快訊
• 定價：
  • 即付即用
  • 404 NOT_FOUND 回應如果位置不在服務範圍內，就會 「不會」計費，但會佔用配額
• 一般使用條款：Google 地圖平台服務條款