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)

可选。指定要启用的预发布功能。

请求正文

请求正文必须为空。

响应正文

针对 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)
}
字段
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)

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

授权范围

需要以下 OAuth 范围：

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

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 中定义的由 3 个字母组成的货币代码。
units

string (int64 format)

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

integer

金额的纳诺 (10^-9) 单位数。这个值必须在 -999999999（含）和 +999999999（含）之间。如果 units 是正数，nanos 必须是正数或零。如果 units 为零，nanos 可以是正数、零或负数。如果 units 是负数，nanos 必须是负数或零。例如，$-1.75 表示为 units=-1 和 nanos=-750000000。

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)

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