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

相应建筑物的资源名称，格式为 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 都描述了屋顶上太阳能板的不同排列方式。它们的排列顺序是按面板数量递增的。SolarPanelConfig（panelsCount=N）基于 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% 分位数、最大值）。值以每年 kWh/kW 为单位，例如 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

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)

此布局中至少带有 1 个面板的每个屋顶板块的生产信息。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 中定义的由 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)

使用假设的折现率，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)

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