Method: buildingInsights.findClosest

查找距离查询点最近的建筑物。如果查询点周围大约 50 米内没有任何建筑物，则返回代码 NOT_FOUND 的错误。

HTTP 请求

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

网址采用 gRPC 转码语法。

查询参数

参数
location

object (LatLng)

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

enum (ImageryQuality)

可选。结果中允许的最低质量级别。不会返回质量低于此值的结果。不指定此属性相当于仅将其限制为“高画质”。

请求正文

请求正文必须为空。

响应正文

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

建筑物的资源名称，格式为 building/<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 千瓦时/千瓦时（其中 kW 是指标准测试条件下的 kW 容量）。
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

屋顶或屋顶分段的面积，以 m^2 为单位。这是屋顶面积（考虑倾斜度），而不是地面底部面积。
sunshineQuantiles[]

number

相应区域内逐点日光度的分位数。如果此处有 N 个值，则表示 (N-1) 列。例如，如果有 5 个值，这些值将是四分位值（最小值、25%、50%、75%、最大值）。值以年度千瓦时/千瓦时为单位，例如 maxSunshineHoursPerYear。
groundAreaMeters2

number

屋顶或屋顶分段覆盖的地面面积，以 m^2 为单位。

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

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

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，表示没有布局。在这种情况下，剩余的子消息将被忽略。

金钱

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

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

string

ISO 4217 中定义的由三个字母组成的货币代码。
units

string (int64 format)

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

integer

金额的纳诺 (10^-9) 单位数。这个值必须在 -999999999（含）和 +999999999（含）之间。如果 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

我们预计太阳能电池板第一年的发电量（以千瓦时为 AC）是多少。
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)

如果使用假设折扣率，20 年期累计节省的现值是多少？
savingsLifetime

object (Money)

面板在整个生命周期内可节省的费用。
presentValueOfSavingsLifetime

object (Money)

按假设折扣率计算，终身累计节省的现值是多少？
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)

在整个有效期内节省了多少（或不节省）多少。