遷移至 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 (已淘汰) EE 圖示
服務上線狀態 已推出 前測 (已淘汰)
存取權
機制 Google Cloud 帳戶，方法是透過 Cloud 控制台啟用 Solar API，並透過「Google 地圖平台」專區管理 API Google Cloud 帳戶，可透過 Cloud 控制台啟用 Earth Engine Solar API
對象 公開 存取權控管
難易度 已自行佈建 Cloud 專案手動存取
驗證機制 API 金鑰和 OAuth API 金鑰
定價
策略 Pay-as-you-go 100；折扣
階層 每 1, 000 次查詢 (價格因用量降低) –
端點 不同端點的價格 –
Cloud
Monitoring 在「Google 地圖平台」底下使用 Cloud Monitoring Cloud Monitoring：在「API 和服務」下方
配額 QPM (每分鐘查詢次數) 和 QPH (每小時查詢次數) 年繳
Logging 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 專案。

只有特定角色才能建立 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 金鑰傳送至存取「新」回應格式網址的要求，如果您省略 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;
  }
}

監控器

專案層級 帳單帳戶層級

Cloud Monitoring Cloud Billing

重要提示

  • 配額：可擴展的用量 (不會消失的每年用量)
    • 目前配額會變更為 QPM
    • 最佳做法：設定用戶端配額及傳送快訊
  • 定價：
    • Pay-as-you-go
    • 404 NOT_FOUND 回應如果位置不在涵蓋範圍內，則不會產生費用，但會佔用配額
  • 一般使用條款：Google 地圖平台服務條款