迁移到 Google Maps Platform 上的 Solar API

如需从 Google Earth Engine Solar API 迁移到 Google Maps Platform Solar API，请执行以下操作：

1. 在您的云项目中启用 Google Maps Platform Solar API。
2. 创建一个新密钥，并将其限制为 GMP Solar API。
3. 请按照以下分步说明更新您的代码。

并列比较

	Solar API（新）	Earth Engine Solar API（已废弃）
发布状态	已发布	测试版（已弃用）
访问
机制	Google Cloud 账号（通过 Cloud 控制台启用 Solar API，并通过“Google Maps Platform”部分管理该 API）	通过 Cloud 控制台启用 Earth Engine Solar API 的 Google Cloud 账号
参与者	公开	受访问权限控制
级别	自行配置	手动访问 Cloud 项目
身份验证	API 密钥和 OAuth	API 密钥
价格
策略	随用随付	100% 折扣
分层	每 1, 000 次查询的价格，价格会随着查询量增加而降低	–
端点	每个端点的价格不同	–
Cloud
监控	“Google Maps Platform”下的云监控	“API 和服务”下的 Cloud Monitoring
配额	QPM（每分钟查询次数）和 QPH（每小时查询次数）	包年
日志记录	Cloud Logging（可选）	Cloud Logging（可选）
结算	Cloud Billing 账号	-
支持	包含 SLO/SLA 的完整 Google Maps Platform 支持	有限，通过电子邮件
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 Maps Platform 条款	Google Earth Engine 条款

分步说明

设置您的 Google Cloud 项目

请参阅以下说明：设置您的 Google Cloud 项目。

注意： 请在“设置 Google Cloud 项目”的“启用 API”部分停止操作。

只有特定角色才能创建 Cloud 项目；如果您无法创建项目，请与贵组织的管理员联系。

您也可以使用现有的 Cloud 项目。如需了解详情，请参阅 Google Maps Platform 使用入门。

设置您的结算账号

请参阅如何管理结算账号中的说明。

您可以将现有 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 Maps Platform 服务条款