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 kWh/kW（其中 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

假设上述面板，此布局在一年中吸收的阳光能量（以直流 kWh 为单位）。
roofSegmentSummaries[]

object (RoofSegmentSummary)

与此布局中至少承载一个面板的每个屋顶路段的生产情况相关的信息。roofSegmentSummaries[i] 描述第 i 个屋顶段，包括其尺寸、预期生产和朝向。

RoofSegmentSummary

建筑物的屋顶部分（其中放置了一些面板）的相关信息。

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

integer

此细分上的面板总数。
yearlyEnergyDcKwh

number

假设上述面板，该布局在一年中捕获的阳光能量（以直流 kWh 为单位）。
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 kWh。
remainingLifetimeUtilityBill

object (Money)

非太阳能发电（电池板使用寿命）的公共事业缴费单。
federalIncentive

object (Money)

可从联邦奖励金抵扣的数额；如果用户购买（无论是否贷款）面板，均适用此金额。
stateIncentive

object (Money)

国家奖励计划可抵扣的金额；如果用户购买（无论是否是贷款）面板，均适用此金额。
utilityIncentive

object (Money)

公共事业奖励项目的可抵扣金额；如果用户购买（无论是否贷款）面板，则适用此金额。
lifetimeSrecTotal

object (Money)

用户在太阳能电池板生命周期内从太阳能电池板上获得的金额；如果用户购买（无论是否为贷款）电池板，则适用该金额。
costOfElectricityWithoutSolar

object (Money)

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

boolean

是否允许净计量。
solarPercentage

number

太阳能供电的用户电力的百分比 (0-100)。适用于第 1 年，但大致适用于未来年份。
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)

生命周期内节省了多少（或未节省）多少。