Method: buildingInsights.findClosest

用于查找形心距离查询点最近的建筑物。如果查询点的大致 50 米范围内没有建筑物，则返回代码为 NOT_FOUND 的错误。

HTTP 请求

GET https://solar.googleapis.com/v1/buildingInsights:findClosest

网址采用 gRPC 转码语法。

查询参数

参数
location

object (LatLng)

必需。API 从中查找最近已知建筑物的经度和纬度。
requiredQuality

enum (ImageryQuality)

可选。结果中允许的最低质量级别。系统不会返回质量低于此值的结果。不指定此值相当于仅限制为高品质。
exactQualityRequired

boolean

可选。是否要求图像的质量完全符合要求。如果设置为 false，则 requiredQuality 字段会被解读为最低所需质量，这样一来，当 requiredQuality 设置为 MEDIUM 时，可能会返回 HIGH 质量的图片。如果设置为 true，则 requiredQuality 会被解读为确切的所需质量，并且如果 requiredQuality 设置为 MEDIUM，则仅返回 MEDIUM 质量的图像。
experiments[]

enum (Experiment)

可选。指定要启用的非正式版实验。使用此字段的请求在《Google Maps Platform 服务专用条款》中被归类为非正式版产品。如需了解详情，请参阅发布阶段说明。
additionalInsights[]

enum (AdditionalInsights)

可选。要包含在响应中的 additionalInsights 列表。

请求正文

请求正文必须为空。

响应正文

针对 Solar.FindClosestBuildingInsights 的响应消息。有关建筑物的位置、尺寸和太阳能板发电潜力的信息。

如果成功，响应正文将包含结构如下的数据：

JSON 表示法 
{
  "name": string,
  "center": {
    object (LatLng)
  },
  "boundingBox": {
    object (LatLngBox)
  },
  "imageryDate": {
    object (Date)
  },
  "imageryProcessedDate": {
    object (Date)
  },
  "postalCode": string,
  "administrativeArea": string,
  "statisticalArea": string,
  "regionCode": string,
  "solarPotential": {
    object (SolarPotential)
  },
  "imageryQuality": enum (ImageryQuality),
  "detectedArrays": {
    object (DetectedArrays)
  }
}
字段
name

string

相应建筑物的资源名称，格式为 buildings/{place_id}。
center

object (LatLng)

建筑物中心附近的点。
boundingBox

object (LatLngBox)

建筑物的边界框。
imageryDate

object (Date)

基础影像的拍摄日期。此值为近似值。
imageryProcessedDate

object (Date)

相应影像的处理完成时间。
postalCode

string

相应建筑物所在的邮政编码（例如美国邮政编码）。
administrativeArea

string

包含相应建筑物的行政区域 1（例如，在美国，指州）。例如，在美国，缩写可能是“MA”或“CA”。
statisticalArea

string

相应建筑所在的统计区域（例如美国人口普查区）。
regionCode

string

相应建筑所在国家/地区（或区域）的区域代码。
solarPotential

object (SolarPotential)

建筑物的太阳能板发电潜力。
imageryQuality

enum (ImageryQuality)

用于计算相应建筑物数据的影像的质量。
detectedArrays

object (DetectedArrays)

在建筑物上检测到的太阳能电池阵列。只有在请求的 FindClosestBuildingInsightsRequest.additional_insights 中包含 DETECTED_ARRAYS 时，系统才会填充此字段。

授权范围

需要以下 OAuth 范围：

  • https://www.googleapis.com/auth/cloud-platform

AdditionalInsights

可在 BuildingInsights 中返回的其他建筑物信息，例如屋顶几何图形和太阳能板阵列。

枚举
ADDITIONAL_INSIGHTS_UNSPECIFIED 默认值。系统将返回默认的 BuildingInsights。
DETECTED_ARRAYS

确定响应是否会包含检测到的数组。

如果指定了此参数，则响应中会填充 detectedArrays 字段。

LatLngBox

以纬度/经度坐标表示的边界框。

JSON 表示法 
{
  "sw": {
    object (LatLng)
  },
  "ne": {
    object (LatLng)
  }
}
字段
sw

object (LatLng)

盒子的西南角。
ne

object (LatLng)

框的东北角。

SolarPotential

有关建筑物太阳能板发电潜力的信息。此文件中的许多字段都是根据“面板”定义的。字段 panelCapacityWatts、panelHeightMeters 和 panelWidthMeters 描述了这些计算中使用的面板模型的参数。

JSON 表示法 
{
  "maxArrayPanelsCount": integer,
  "panelCapacityWatts": number,
  "panelHeightMeters": number,
  "panelWidthMeters": number,
  "panelLifetimeYears": integer,
  "maxArrayAreaMeters2": number,
  "maxSunshineHoursPerYear": number,
  "carbonOffsetFactorKgPerMwh": number,
  "wholeRoofStats": {
    object (SizeAndSunshineStats)
  },
  "buildingStats": {
    object (SizeAndSunshineStats)
  },
  "roofSegmentStats": [
    {
      object (RoofSegmentSizeAndSunshineStats)
    }
  ],
  "solarPanels": [
    {
      object (SolarPanel)
    }
  ],
  "solarPanelConfigs": [
    {
      object (SolarPanelConfig)
    }
  ],
  "financialAnalyses": [
    {
      object (FinancialAnalysis)
    }
  ]
}
字段
maxArrayPanelsCount

integer

最大阵列的大小，即屋顶上可安装的面板数量上限。
panelCapacityWatts

number

计算中使用的太阳能板的功率（以瓦为单位）。
panelHeightMeters

number

计算中使用的面板在竖屏方向上的高度（以米为单位）。
panelWidthMeters

number

计算中使用的面板在纵向模式下的宽度（以米为单位）。
panelLifetimeYears

integer

太阳能电池板的预期使用寿命（以年为单位）。此值用于财务计算。
maxArrayAreaMeters2

number

最大阵列的面积（以平方米为单位）。
maxSunshineHoursPerYear

number

屋顶上任何一点每年接收到的日照时数上限。日照时数是指每年接收到的总日照量（能量）。1 个日照小时 = 1 千瓦时/千瓦（其中千瓦是指标准测试条件下的容量）。
carbonOffsetFactorKgPerMwh

number

每兆瓦时电网电力产生的等量二氧化碳。此指标衡量的是太阳能发电所取代的电网电力的碳强度。
wholeRoofStats

object (SizeAndSunshineStats)

分配给某个屋顶段的屋顶部分的总大小和日照分位数。尽管名称如此，但此位置可能不包括整个建筑物。请参阅 buildingStats。
buildingStats

object (SizeAndSunshineStats)

整个建筑物的面积和日照分位数，包括未分配给任何屋顶段的部分屋顶。由于这些部件的方向未得到很好的表征，因此屋顶面积估计值不可靠，但地面面积估计值可靠。通过将 wholeRoofStats 中的屋顶面积按 buildingStats 和 wholeRoofStats 的地面面积比进行缩放，可以获得更可靠的整个建筑物的屋顶面积。
roofSegmentStats[]

object (RoofSegmentSizeAndSunshineStats)

每个屋顶段的大小和日照分位数。
solarPanels[]

object (SolarPanel)

每个 SolarPanel 都描述了一个太阳能板。它们按面板布局算法放置的顺序列出。这些结果通常（但并非总是）按年发电量降序排列。
solarPanelConfigs[]

object (SolarPanelConfig)

每个 SolarPanelConfig 都描述了屋顶上不同的太阳能电池板排列方式。它们按面板数量递增的顺序排列。panelsCount=N 的 SolarPanelConfig 基于 solarPanels 列表中的前 N 个面板。只有当屋顶上至少可以安装 4 块太阳能板时，系统才会填充此字段。
financialAnalyses[]

object (FinancialAnalysis)

FinancialAnalysis 表示假设给定每月账单和给定电力供应商的情况下，改用太阳能可节省的费用。它们按每月账单金额的升序排列。如果 Solar API 没有足够的信息来执行财务计算，则对于相应区域内的建筑物，此字段将为空。

SizeAndSunshineStats

屋顶或部分屋顶的大小和日照程度分位数。

JSON 表示法 
{
  "areaMeters2": number,
  "sunshineQuantiles": [
    number
  ],
  "groundAreaMeters2": number
}
字段
areaMeters2

number

屋顶或屋顶部分的面积（以平方米为单位）。这是屋顶面积（考虑倾斜度），而不是地面占地面积。
sunshineQuantiles[]

number

相应区域内各点的日照分位数。如果此处有 N 个值，则表示 (N-1) 分位数。例如，如果有 5 个值，则它们将是四分位数（最小值、25%、50%、75%、最大值）。值以每年每千瓦时的形式表示，例如 maxSunshineHoursPerYear。
groundAreaMeters2

number

屋顶或屋顶段覆盖的地面占地面积（以平方米为单位）。

RoofSegmentSizeAndSunshineStats

有关屋顶段的大小和日照分位数的信息。

JSON 表示法 
{
  "stats": {
    object (SizeAndSunshineStats)
  },
  "center": {
    object (LatLng)
  },
  "boundingBox": {
    object (LatLngBox)
  },
  "pitchDegrees": number,
  "azimuthDegrees": number,
  "planeHeightAtCenterMeters": number
}
字段
stats

object (SizeAndSunshineStats)

屋顶段的总大小和日照分位数。
center

object (LatLng)

屋顶段中心附近的点。
boundingBox

object (LatLngBox)

屋顶段的边界框。
pitchDegrees

number

屋顶段相对于理论地平面的角度。0 = 与地面平行，90 = 与地面垂直。
azimuthDegrees

number

屋顶段所指的罗盘方向。0 = 北，90 = 东，180 = 南。对于“平坦”的屋顶段（pitchDegrees 非常接近 0），方位角未明确定义，因此为了保持一致性，我们将其任意定义为 0（正北）。
planeHeightAtCenterMeters

number

由 center 指定的点处的屋顶段平面的高度（以米为单位，高于海平面）。与俯仰角、方位角和中心位置一起，可完全定义屋顶段平面。

SolarPanel

SolarPanel 用于描述单个太阳能板的位置、方向和发电量。如需了解面板的参数，请参阅 SolarPotential 中的 panelHeightMeters、panelWidthMeters 和 panelCapacityWatts 字段。

JSON 表示法 
{
  "center": {
    object (LatLng)
  },
  "orientation": enum (SolarPanelOrientation),
  "yearlyEnergyDcKwh": number,
  "segmentIndex": integer
}
字段
center

object (LatLng)

面板的中心。
orientation

enum (SolarPanelOrientation)

面板的方向。
yearlyEnergyDcKwh

number

此布局在一年内捕获的阳光能量（以直流千瓦时为单位）。
segmentIndex

integer

roofSegmentStats 中与放置此面板的屋顶段相对应的 RoofSegmentSizeAndSunshineStats 的索引。

SolarPanelOrientation

太阳能板的方向。此值必须相对于放置面板的屋顶段的方位角进行解读。

枚举
SOLAR_PANEL_ORIENTATION_UNSPECIFIED 面板方向未知。
LANDSCAPE LANDSCAPE 面板的长边垂直于其所放置的屋顶段的方位角方向。
PORTRAIT PORTRAIT 面板的长边与放置它的屋顶段的方位角方向平行。

SolarPanelConfig

SolarPanelConfig 用于描述屋顶上太阳能电池板的特定放置位置。

JSON 表示法 
{
  "panelsCount": integer,
  "yearlyEnergyDcKwh": number,
  "roofSegmentSummaries": [
    {
      object (RoofSegmentSummary)
    }
  ]
}
字段
panelsCount

integer

面板总数。请注意，此字段与 roofSegmentSummaries 中相应字段（的总和）是冗余的。
yearlyEnergyDcKwh

number

在假设使用上述电池板的情况下，此布局在一年内捕获的太阳能能量（以直流千瓦时为单位）。
roofSegmentSummaries[]

object (RoofSegmentSummary)

有关此布局中至少搭载一个太阳能板的每个屋顶段的生产信息。roofSegmentSummaries[i] 描述第 i 个屋顶段，包括其大小、预期产量和朝向。

RoofSegmentSummary

有关建筑物上屋顶段的信息，其中放置了一些面板。

JSON 表示法 
{
  "panelsCount": integer,
  "yearlyEnergyDcKwh": number,
  "pitchDegrees": number,
  "azimuthDegrees": number,
  "segmentIndex": integer
}
字段
panelsCount

integer

相应细分中的面板总数。
yearlyEnergyDcKwh

number

布局的这一部分在一年内捕获的太阳光能量（以直流千瓦时为单位），假设采用上述电池板。
pitchDegrees

number

屋顶段相对于理论地平面的角度。0 = 与地面平行，90 = 与地面垂直。
azimuthDegrees

number

屋顶段所指的罗盘方向。0 = 北，90 = 东，180 = 南。对于“平坦”的屋顶段（pitchDegrees 非常接近 0），方位角未明确定义，因此为了保持一致性，我们将其任意定义为 0（正北）。
segmentIndex

integer

相应 RoofSegmentSizeAndSunshineStats 在 roofSegmentStats 中的索引。

FinancialAnalysis

针对特定电费金额的最佳太阳能布局的成本和效益分析。

JSON 表示法 
{
  "monthlyBill": {
    object (Money)
  },
  "defaultBill": boolean,
  "averageKwhPerMonth": number,
  "financialDetails": {
    object (FinancialDetails)
  },
  "leasingSavings": {
    object (LeasingSavings)
  },
  "cashPurchaseSavings": {
    object (CashPurchaseSavings)
  },
  "financedPurchaseSavings": {
    object (FinancedPurchaseSavings)
  },
  "panelConfigIndex": integer
}
字段
monthlyBill

object (Money)

此分析假设的每月电费。
defaultBill

boolean

相应账单大小是否被选为相应建筑所在区域的默认账单大小。BuildingSolarPotential 中应只有一个 FinancialAnalysis 设置了 defaultBill。
averageKwhPerMonth

number

根据账单金额和当地电费，估算住宅在平均每月使用的电量。
financialDetails

object (FinancialDetails)

无论使用何种融资方式，都适用的财务信息。
leasingSavings

object (LeasingSavings)

租赁太阳能板的费用和好处。
cashPurchaseSavings

object (CashPurchaseSavings)

现金购买太阳能板的成本和收益。
financedPurchaseSavings

object (FinancedPurchaseSavings)

通过融资购买太阳能板的成本和收益。
panelConfigIndex

integer

相应账单金额的最佳太阳能布局在 solarPanelConfigs 中的索引。可以是 -1，表示没有布局。在这种情况下，其余子消息将被省略。

Money

表示含有货币类型的金额。

JSON 表示法 
{
  "currencyCode": string,
  "units": string,
  "nanos": integer
}
字段
currencyCode

string

采用 ISO 4217 标准定义的三位字母货币代码。
units

string (int64 format)

金额的整数单位。例如，如果 currencyCode 是 "USD"，则 1 单位就是一美元。
nanos

integer

以纳单位 (10^-9) 表示的金额数量。取值范围必须在 -999,999,999 至 +999,999,999 之间（含边界值）。如果 units 是正数，nanos 必须是正数或零。如果 units 为零，nanos 可以是正数、零或负数。如果 units 是负数，nanos 必须是负数或零。例如，$-1.75 表示为 units=-1 和 nanos=-750,000,000。

FinancialDetails

财务分析的详细信息。其中一些详细信息已存储在更高级别（例如自付费用）。总金额是指在 SolarPotential 中由 panelLifetimeYears 字段定义的整个生命周期内的总金额。注意：购买平板电脑的自付费用在 CashPurchaseSavings 的 outOfPocketCost 字段中给出。

JSON 表示法 
{
  "initialAcKwhPerYear": number,
  "remainingLifetimeUtilityBill": {
    object (Money)
  },
  "federalIncentive": {
    object (Money)
  },
  "stateIncentive": {
    object (Money)
  },
  "utilityIncentive": {
    object (Money)
  },
  "lifetimeSrecTotal": {
    object (Money)
  },
  "costOfElectricityWithoutSolar": {
    object (Money)
  },
  "netMeteringAllowed": boolean,
  "solarPercentage": number,
  "percentageExportedToGrid": number
}
字段
initialAcKwhPerYear

number

我们认为太阳能板在第一年将产生的交流电千瓦时数。
remainingLifetimeUtilityBill

object (Money)

太阳能板使用寿命期间，非太阳能发电的公共事业缴费单。
federalIncentive

object (Money)

联邦政府奖励提供的资金金额；如果用户购买（无论是否贷款）太阳能板，则适用此金额。
stateIncentive

object (Money)

州政府奖励计划提供的资金金额；如果用户购买（无论是否贷款）太阳能板，则适用此奖励。
utilityIncentive

object (Money)

公用事业公司奖励提供的金额；如果用户购买（无论是否贷款）太阳能板，则适用此金额。
lifetimeSrecTotal

object (Money)

用户在太阳能板使用寿命内将从太阳能可再生能源信用证中获得的金额；如果用户购买（无论是否贷款）太阳能板，则适用此值。
costOfElectricityWithoutSolar

object (Money)

如果用户未安装太阳能板，在整个生命周期内需要支付的电费总额。
netMeteringAllowed

boolean

是否允许净计量。
solarPercentage

number

用户电力中太阳能所占的百分比（0-100）。适用于第一年，但对于未来年份来说，只是近似正确。
percentageExportedToGrid

number

根据第一季度的发电量，我们假设输送到电网的太阳能发电量所占的百分比（0-100）。如果不允许净计量，这会影响计算结果。

LeasingSavings

租赁特定配置的太阳能板（具有特定用电量）的成本和收益。

JSON 表示法 
{
  "leasesAllowed": boolean,
  "leasesSupported": boolean,
  "annualLeasingCost": {
    object (Money)
  },
  "savings": {
    object (SavingsOverTime)
  }
}
字段
leasesAllowed

boolean

相应司法管辖区是否允许租赁（某些州不允许租赁）。如果此字段为 false，则应忽略相应消息中的值。
leasesSupported

boolean

金融计算引擎是否支持相应司法管辖区的租赁。如果此字段为 false，则应忽略相应消息中的值。这与 leasesAllowed 无关：在某些地区，允许租赁，但租赁条件不在财务模型的处理范围内。
annualLeasingCost

object (Money)

预计年度租赁费用。
savings

object (SavingsOverTime)

在整个生命周期内节省（或未节省）的费用。

SavingsOverTime

不同融资方式之间共享的财务信息。

JSON 表示法 
{
  "savingsYear1": {
    object (Money)
  },
  "savingsYear20": {
    object (Money)
  },
  "presentValueOfSavingsYear20": {
    object (Money)
  },
  "savingsLifetime": {
    object (Money)
  },
  "presentValueOfSavingsLifetime": {
    object (Money)
  },
  "financiallyViable": boolean
}
字段
savingsYear1

object (Money)

安装太阳能板后第一年的节省金额。
savingsYear20

object (Money)

安装太阳能板后前 20 年的节省金额。
presentValueOfSavingsYear20

object (Money)

假设折扣率为 5%，那么 20 年累计节省的费用按现值计算是多少？
savingsLifetime

object (Money)

整个面板生命周期内的节省金额。
presentValueOfSavingsLifetime

object (Money)

假设折扣率为 10%，累计生命周期节省的现值是多少？
financiallyViable

boolean

指示相应方案在财务上是否可行。如果财务可行性较差（例如亏损），则为 false。

CashPurchaseSavings

直接购买特定配置的太阳能板（具有特定用电量）的成本和效益。

JSON 表示法 
{
  "outOfPocketCost": {
    object (Money)
  },
  "upfrontCost": {
    object (Money)
  },
  "rebateValue": {
    object (Money)
  },
  "savings": {
    object (SavingsOverTime)
  },
  "paybackYears": number
}
字段
outOfPocketCost

object (Money)

税前税收优惠前的初始费用：必须自掏腰包支付的金额。与税后激励 upfrontCost 相对。
upfrontCost

object (Money)

扣除税收优惠后的初始费用：指第一年必须支付的金额。与税前激励 outOfPocketCost 相对。
rebateValue

object (Money)

所有退税的总金额。
savings

object (SavingsOverTime)

在整个生命周期内节省（或未节省）的费用。
paybackYears

number

投资回收年限。负值表示在生命周期内永远不会发生投资回报。

FinancedPurchaseSavings

使用贷款购买特定配置的太阳能板（具有特定用电量）的成本和收益。

JSON 表示法 
{
  "annualLoanPayment": {
    object (Money)
  },
  "rebateValue": {
    object (Money)
  },
  "loanInterestRate": number,
  "savings": {
    object (SavingsOverTime)
  }
}
字段
annualLoanPayment

object (Money)

年度贷款还款。
rebateValue

object (Money)

所有税收返还（包括联邦投资税收抵免 [ITC]）的价值。
loanInterestRate

number

这组计算中假设的贷款利率。
savings

object (SavingsOverTime)

在整个生命周期内节省（或未节省）的费用。

DetectedArrays

有关在建筑物上检测到的太阳能电池阵列的信息。

JSON 表示法 
{
  "detectionStatus": enum (DetectionStatus),
  "latestCaptureDate": {
    object (Date)
  }
}
字段
detectionStatus

enum (DetectionStatus)

指示相应建筑的太阳能电池阵列的检测状态。
latestCaptureDate

object (Date)

指示最新太阳能阵列数据捕获日期的日期。

DetectionStatus

指示相应建筑的太阳能电池阵列的检测状态。

枚举
DETECTION_STATUS_UNSPECIFIED 未指定状态。
DETECTION_STATUS_DATA_UNAVAILABLE 没有此建筑物的检测到的太阳能电池阵列数据。
DETECTION_STATUS_ARRAYS_DETECTED 已检测到此建筑至少有一个太阳能电池阵列。
DETECTION_STATUS_NO_ARRAYS_DETECTED 未检测到此建筑物的任何太阳能电池阵列。